fabricjs/fabric.js · error · FabricError

Failed to create `canvas` element

Error message

Failed to create `canvas` element

What it means

Thrown by createCanvasElement when document.createElement('canvas') returns nothing usable or the element lacks a getContext method. It guards against environments where the DOM document cannot create real canvas elements, e.g. SSR or a mocked/hacked document. Fabric uses it internally for every offscreen canvas it creates.

Source

Thrown at packages/core/src/util/misc/dom.ts:11

import { getFabricDocument } from '../../env';
import type { ImageFormat, TSize } from '../../typedefs';
import { FabricError } from '../internals/console';
/**
 * Creates canvas element
 * @return {CanvasElement} initialized canvas element
 */
export const createCanvasElement = (): HTMLCanvasElement => {
  const element = getFabricDocument().createElement('canvas');
  if (!element || typeof element.getContext === 'undefined') {
    throw new FabricError('Failed to create `canvas` element');
  }
  return element;
};

/**
 * Creates image element (works on client and node)
 * @return {HTMLImageElement} HTML image element
 */
export const createImage = (): HTMLImageElement =>
  getFabricDocument().createElement('img');

/**
 * Creates a canvas element that is a copy of another and is also painted
 * @param {CanvasElement} canvas to copy size and content of
 * @return {CanvasElement} initialized canvas element
 */
export const copyCanvasElement = (
  canvas: HTMLCanvasElement,

View on GitHub (pinned to 2bd4992cab)

Solutions

1. In Node/SSR, install and register node-canvas: npm install canvas (fabric's node build uses it automatically)
2. In jsdom tests, install 'jest-canvas-mock' or the 'canvas' npm package so createElement('canvas') works
3. Avoid calling canvas-dependent fabric APIs during SSR; render only on the client after mount
4. If you called setFabricDocument with a custom document, ensure its createElement returns real canvas elements

Example fix

// before (Node SSR)
import { FabricImage } from 'fabric';
const img = new FabricImage(...); // throws: Failed to create `canvas` element

// after
npm install canvas
// and use fabric's node entry (dist/index.min.mjs for node) so document/canvas are provided

const supportsCanvas = () => {
  try {
    const c = document.createElement('canvas');
    return !!c && typeof c.getContext === 'function';
  } catch { return false; }
};
if (!supportsCanvas()) { /* run non-canvas path */ }

const hasCanvasSupport = (): boolean =>
  typeof document !== 'undefined' &&
  typeof document.createElement === 'function' &&
  typeof document.createElement('canvas')?.getContext === 'function';

try {
  const el = fabric.util.createCanvasElement();
} catch (e) {
  if (e instanceof Error && e.message.includes('`canvas` element')) {
    // environment lacks canvas: install node-canvas or defer to client
  } else throw e;
}

When it happens

Trigger: Running fabric on the server without node-canvas configured (getFabricDocument() returns a document stub), jsdom test environments without canvas support, or custom setFabricDocument() to an object missing proper createElement. Indirectly triggered by many APIs: filters, text measurement, image resizing, toDataURL.

Common situations: Server-side rendering with fabric without installing the 'canvas' (node-canvas) package, Jest/jsdom tests without the 'canvas' test-environment patch, or mocking global document in Node.

Related errors

• Fabric env was not initialized. Import fabric, fabric/node,
• Trying to initialize a canvas that has already been initiali

AI-assisted analysis of fabricjs/fabric.js@2bd4992cab (2026-08-28). Data as JSON: /api/errors/94e24d3ab4bd8fe9. Report an issue: GitHub.