---
title: "Chart.js — type:time Axis Requires a Date Adapter"
aliases: [chartjs-time-axis, chartjs-date-adapter, chartjs-adapter-date-fns, chartjs-silent-failure]
tags: [chartjs, javascript, frontend, dashboard, time-series, debugging]
sources:
  - "daily/2026-04-21.md"
created: 2026-04-21
updated: 2026-04-21
---

# Chart.js — type:time Axis Requires a Date Adapter

Chart.js does not bundle a date/time parsing library. When a chart uses `type: 'time'` on an axis (common for time-series dashboards), Chart.js requires an external date adapter to be registered. Without it, the chart initialization crashes silently in JavaScript before any data is rendered — the canvas element renders blank with no visible error in the chart itself.

## Key Points

- **`type: 'time'` axis fails silently without a registered date adapter** — no visible error in the chart; JavaScript throws internally but the chart just renders blank
- **`chartjs-adapter-date-fns`** is the most common adapter — requires importing both `chart.js` and `chartjs-adapter-date-fns`; the adapter registers itself on import
- The blank canvas symptom is identical to "no data" — always check for a missing adapter before debugging data fetching or chart config
- **`chart.js/auto` import is NOT sufficient** — the auto bundle includes Chart.js with all chart types but still excludes the date adapter
- The adapter must be imported before `new Chart(...)` is called; it registers itself globally via side effect

## Details

### The Failure Mode

```js
// Chart config with time axis
const config = {
  type: 'line',
  data: { datasets: [/* ... */] },
  options: {
    scales: {
      x: {
        type: 'time',          // ← requires date adapter
        time: { unit: 'hour' }
      }
    }
  }
};

new Chart(ctx, config);
// If adapter is missing: Chart.js throws internally
// "Error: This method is not implemented: Check that a complete date adapter is provided"
// The canvas stays blank — no user-visible error if exception is caught silently
```

### The Fix

```js
// 1. Install the adapter
// npm install chartjs-adapter-date-fns date-fns
// or
// <script src="https://cdn.jsdelivr.net/npm/chartjs-adapter-date-fns/dist/chartjs-adapter-date-fns.bundle.min.js"></script>

// 2. Import it before using Chart.js — it self-registers
import 'chartjs-adapter-date-fns';
import { Chart } from 'chart.js';

// Now type: 'time' works correctly
new Chart(ctx, config);
```

For CDN / script tag usage (no bundler):
```html
<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
<!-- Must come AFTER chart.js, BEFORE your chart code -->
<script src="https://cdn.jsdelivr.net/npm/chartjs-adapter-date-fns/dist/chartjs-adapter-date-fns.bundle.min.js"></script>
<script src="your-chart-code.js"></script>
```

### Why the Failure Is Silent

Chart.js catches the adapter error internally and attempts to degrade gracefully. The error message `"This method is not implemented"` may appear in the browser console (F12 → Console), but:
1. Dashboard apps often have global error handlers that suppress console output
2. The chart canvas is present and sized correctly — it just has no content
3. It looks identical to "data is empty" or "data fetch failed"

Always open browser DevTools → Console before assuming the data pipeline is broken.

### Alternative Adapters

| Adapter | Library | Bundle Size |
|---------|---------|-------------|
| `chartjs-adapter-date-fns` | date-fns | ~8 KB (bundled) |
| `chartjs-adapter-luxon` | Luxon | ~14 KB |
| `chartjs-adapter-moment` | Moment.js | ~30 KB+ |
| `chartjs-adapter-dayjs` | Day.js | ~4 KB |

`chartjs-adapter-date-fns` is the standard recommendation for new projects — date-fns is tree-shakable and the combined bundle is small.

### Context: Power & Cost Dashboard (2026-04-21)

A homelab monitoring dashboard used Chart.js with `type: 'time'` on the X axis to display power consumption over time. The `refresh()` function that fetched data from Prometheus never ran because the chart initialization threw before reaching it. The symptom was a completely blank dashboard — no charts, no errors displayed. Adding `chartjs-adapter-date-fns` resolved the initialization crash and all charts appeared.

## Related Concepts

- [[wiki/concepts/prometheus-joules-watts-gotcha]] — the other Chart.js dashboard bug found in the same session (wrong units)
- [[wiki/concepts/beszel-monitoring-deployment]] — Beszel as a monitoring alternative that doesn't require Chart.js setup
- [[wiki/homelab/_index]] — homelab monitoring stack context

## Sources

- [[daily/2026-04-21.md]] — Power & Cost dashboard blank due to Chart.js `type: 'time'` crash; missing `chartjs-adapter-date-fns`; adding the adapter resolved the initialization crash and data loaded correctly
