Troubleshooting
What to check when a chart does not appear or looks wrong, by what you see on screen.
Each heading is what you see on screen.
An error says components must be rendered inside ChartsProvider
The full message is EmKit components must be rendered inside <ChartsProvider>. A chart is being rendered outside the provider. Wrap the app in it, as in step 2 of the quick start.
An error says createContext only works in Client Components
This is Next.js, which renders every file as a Server Component unless it says otherwise, and the components read React context. Render ChartsProvider from a client file rendered by app/layout.tsx, and put 'use client'; on the first line of every file that renders a chart, as in the quick start. The package does not add the directive itself.
On the server, a chart renders as its card, with its title and an empty <canvas> that Chart.js draws in the browser; a KPI renders its number and a paginated table its rows. Three components wait for the browser: the scrollable table shows its empty state until it hydrates, and the donut and the donut with total draw their chart after they mount.
Next.js says hydration failed, or that text did not match
The server and the browser formatted a number differently, because their locales differ, and React threw the server’s HTML away. Pin the locale in the provider, theme={{ formatter: { locale: 'en-US' } }}, as in the client file, or pass the reader’s locale from the request.
A server-rendered heat map has black cells
A colour you passed as a name, rgb() or var(), such as minColor="mediumpurple", renders black on the server, and React keeps the server’s colours. Pass hex colours, such as '#f4f0ff', for minColor, midColor, maxColor and the theme’s chart colours; the defaults are hex already. Or render the heat map in the browser only, with next/dynamic(() => import('./HeatMapCard'), { ssr: false }) from a client file.
Chart text is in a serif or system font
The provider loads Inter when it mounts: a stylesheet from fonts.googleapis.com and the font files from fonts.gstatic.com. If a network or a content security policy blocks them, charts draw in the system sans-serif font. A policy needs https://fonts.googleapis.com in style-src and https://fonts.gstatic.com in font-src.
To stop the request or serve the font yourself, replace theme.fonts: an empty google list turns the request off, and custom adds an @font-face from your own file.
import type { ReactNode } from 'react';
import { ChartsProvider } from 'em-kit';
const theme = {
fonts: {
google: [], // no request to Google Fonts
custom: [
{
family: 'Inter',
src: '/fonts/inter-variable.woff2',
descriptors: { weight: '100 900' },
},
],
},
};
export function SelfHostedFont({ children }: { children: ReactNode }) {
return <ChartsProvider theme={theme}>{children}</ChartsProvider>;
}The chart is squashed to about 150 pixels tall
A chart fills its parent, and the parent has no height. Give the parent one, for example style={{ height: 360 }}.
The chart is squashed to about 300 pixels wide
A chart fills its parent’s width, and the parent sits in a flex item with no width of its own, for example under display: flex; place-items: center. Give the flex item itself a width, such as #root { width: 100% }, or remove the centring. A width on the chart’s own wrapper does not help: it is a share of the same shrunken item.
The time axis shows raw timestamps
Labels such as 2026-01-01T00:00:00.000Z mean a time value has a Z, an offset, or is not a full timestamp. Send YYYY-MM-DDTHH:mm:ss.SSS with nothing after it. See time values.
A time chart draws its axis but no bars or line
The time values are not the start of each period, so no row matches a period on the axis. For month, send the first day of the month at 00:00:00.000. See time values.
A time chart shows one empty period
The rows have no key that matches the dimension’s name, so the chart falls back to the current period. Use the same string for the row key and for name.
A chart grouped by a time field shows no bars
A time dimension used as groupBy is read from the key name.granularity, such as month.month. Add that key to each row. See time as the grouping field.
The skeleton never goes away
results.isLoading is still true, or results() was called before the rows arrived. Pass { isLoading: false, data: rows } once they do. See Loading, empty and errors.