fabricjs/fabric.js · error · FabricError

Fabric env was not initialized. Import fabric, fabric/node,

Error message

Fabric env was not initialized. Import fabric, fabric/node, @fabricjs/browser, or @fabricjs/node before using environment-dependent APIs, or call setEnv/setEnvFactory.

What it means

Fabric.js core is environment-agnostic: it lazily initializes a DOM/window environment (`env`) either by importing a platform entry point (fabric, fabric/node, @fabricjs/browser, @fabricjs/node) or by calling `setEnv`/`setEnvFactory`. If an environment-dependent API (e.g. getFabricDocument) is used before any env is set, `getEnv()` throws this error.

Source

Thrown at packages/core/src/env/index.ts:41

};

/**
 * Sets the environment factory used by package entrypoints.
 *
 * **CAUTION**: Must be called before using APIs that access the environment.
 */
export const setEnvFactory = (factory: () => TFabricEnv) => {
  envFactory = factory;
};

export const getEnv = () => {
  if (env) {
    return env;
  }
  if (envFactory) {
    return (env = envFactory());
  }
  throw new FabricError(
    'Fabric env was not initialized. Import fabric, fabric/node, @fabricjs/browser, or @fabricjs/node before using environment-dependent APIs, or call setEnv/setEnvFactory.',
  );
};

export const getFabricDocument = (): Document => getEnv().document;

export const getFabricWindow = (): TFabricWindow => getEnv().window;

/**
 * @returns the config value if defined, fallbacks to the environment value
 */
export const getDevicePixelRatio = () =>
  Math.max(
    config.devicePixelRatio ?? getFabricWindow().devicePixelRatio ?? 1,
    1,
  );

export type * from './types';

View on GitHub (pinned to 2bd4992cab)

Solutions

1. Import a full entry point before using env-dependent APIs: `import { Canvas } from 'fabric'` (browser) or `import { ... } from 'fabric/node'` / `@fabricjs/node` under Node.
2. For custom/test environments, call `setEnv(yourEnv)` or `setEnvFactory(() => env)` (e.g. jsdom/happy-dom) before any fabric usage.
3. Check import order: side-effect entry modules must execute before core API calls; avoid importing deep internal paths that bypass the entry point.
4. In SSR frameworks, guard fabric usage so it only runs on the client (or explicitly set up the node env).

Example fix

// before
import { StaticCanvas } from '@fabricjs/core'; // deep/core-only import
const doc = getFabricDocument(); // throws: env not initialized

// after
import { StaticCanvas } from 'fabric'; // browser entry sets env
// or under Node:
// import { StaticCanvas } from 'fabric/node';
const doc = getFabricDocument();

import { getEnv } from 'fabric';
let envReady = true;
try { getEnv(); } catch { envReady = false; }
if (!envReady) {
  // import 'fabric/node' or call setEnvFactory(() => new JSDOM().window)
}

const hasEnv = (): boolean => {
  try { getEnv(); return true; } catch { return false; }
};

import { getFabricDocument } from 'fabric';
try {
  const doc = getFabricDocument();
} catch (e) {
  if (e instanceof Error && e.message.includes('Fabric env was not initialized')) {
    // add the correct entry-point import (fabric / fabric/node) or setEnv(), then retry
  } else throw e;
}

When it happens

Trigger: Importing only `@fabricjs/core` (or deep paths like 'fabric/dist/index.min.js' equivalents) and then calling APIs that need `document`/`window` (canvas creation, DOM manager, fabric.document). Also running under Node without importing `@fabricjs/node` or calling `setEnvFactory`, or importing core before the env-setting module due to module ordering/tree-shaking.

Common situations: SSR (Next.js/Nuxt) server-side render touching fabric core APIs without the node env; mixing package entry points after upgrading to the modular @fabricjs/* packages; tests importing internal core modules directly; custom environments (workers, happy-dom/jsdom) not wired via setEnvFactory.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• Failed to create `canvas` element
• No class registered for ${classType}
• Trying to initialize a canvas that has already been initiali
• Vertex, fragment shader or program creation error
• Vertex shader compile error for ${this.type}: ${gl.getShader

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