{"record":{"id":"94e24d3ab4bd8fe9","repo":"fabricjs/fabric.js","slug":"failed-to-create-canvas-element","errorCode":null,"errorMessage":"Failed to create `canvas` element","messagePattern":"Failed to create `canvas` element","errorType":"exception","errorClass":"FabricError","httpStatus":null,"severity":"error","filePath":"packages/core/src/util/misc/dom.ts","lineNumber":11,"sourceCode":"import { getFabricDocument } from '../../env';\nimport type { ImageFormat, TSize } from '../../typedefs';\nimport { FabricError } from '../internals/console';\n/**\n * Creates canvas element\n * @return {CanvasElement} initialized canvas element\n */\nexport const createCanvasElement = (): HTMLCanvasElement => {\n  const element = getFabricDocument().createElement('canvas');\n  if (!element || typeof element.getContext === 'undefined') {\n    throw new FabricError('Failed to create `canvas` element');\n  }\n  return element;\n};\n\n/**\n * Creates image element (works on client and node)\n * @return {HTMLImageElement} HTML image element\n */\nexport const createImage = (): HTMLImageElement =>\n  getFabricDocument().createElement('img');\n\n/**\n * Creates a canvas element that is a copy of another and is also painted\n * @param {CanvasElement} canvas to copy size and content of\n * @return {CanvasElement} initialized canvas element\n */\nexport const copyCanvasElement = (\n  canvas: HTMLCanvasElement,","sourceCodeStart":1,"sourceCodeEnd":29,"githubUrl":"https://github.com/fabricjs/fabric.js/blob/2bd4992cabf4ec9609aa349ea09b723cadc94bef/packages/core/src/util/misc/dom.ts#L1-L29","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["In Node/SSR, install and register node-canvas: npm install canvas (fabric's node build uses it automatically)","In jsdom tests, install 'jest-canvas-mock' or the 'canvas' npm package so createElement('canvas') works","Avoid calling canvas-dependent fabric APIs during SSR; render only on the client after mount","If you called setFabricDocument with a custom document, ensure its createElement returns real canvas elements"],"exampleFix":"// before (Node SSR)\nimport { FabricImage } from 'fabric';\nconst img = new FabricImage(...); // throws: Failed to create `canvas` element\n\n// after\nnpm install canvas\n// and use fabric's node entry (dist/index.min.mjs for node) so document/canvas are provided","handlingStrategy":"validation","validationCode":"const supportsCanvas = () => {\n  try {\n    const c = document.createElement('canvas');\n    return !!c && typeof c.getContext === 'function';\n  } catch { return false; }\n};\nif (!supportsCanvas()) { /* run non-canvas path */ }","typeGuard":"const hasCanvasSupport = (): boolean =>\n  typeof document !== 'undefined' &&\n  typeof document.createElement === 'function' &&\n  typeof document.createElement('canvas')?.getContext === 'function';","tryCatchPattern":"try {\n  const el = fabric.util.createCanvasElement();\n} catch (e) {\n  if (e instanceof Error && e.message.includes('`canvas` element')) {\n    // environment lacks canvas: install node-canvas or defer to client\n  } else throw e;\n}","preventionTips":["Install node-canvas when running fabric in Node/SSR","In jsdom tests use jest-canvas-mock or the canvas package","Gate canvas-dependent fabric calls behind client-only code paths","Don't replace setFabricDocument with a stub lacking real createElement"],"tags":["canvas","ssr","node","dom","environment"],"backgroundTag":"missing-dom-environment","analyzedSha":"2bd4992cabf4ec9609aa349ea09b723cadc94bef","analyzedAt":"2026-08-28T10:56:44.286Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}