{"record":{"id":"f4d5d18a04f9d47c","repo":"fabricjs/fabric.js","slug":"fabric-env-was-not-initialized-import-fabric-fab","errorCode":null,"errorMessage":"Fabric env was not initialized. Import fabric, fabric/node, @fabricjs/browser, or @fabricjs/node before using environment-dependent APIs, or call setEnv/setEnvFactory.","messagePattern":"Fabric env was not initialized\\. Import fabric, fabric/node, @fabricjs/browser, or @fabricjs/node before using environment-dependent APIs, or call setEnv/setEnvFactory\\.","errorType":"exception","errorClass":"FabricError","httpStatus":null,"severity":"error","filePath":"packages/core/src/env/index.ts","lineNumber":41,"sourceCode":"};\n\n/**\n * Sets the environment factory used by package entrypoints.\n *\n * **CAUTION**: Must be called before using APIs that access the environment.\n */\nexport const setEnvFactory = (factory: () => TFabricEnv) => {\n  envFactory = factory;\n};\n\nexport const getEnv = () => {\n  if (env) {\n    return env;\n  }\n  if (envFactory) {\n    return (env = envFactory());\n  }\n  throw new FabricError(\n    'Fabric env was not initialized. Import fabric, fabric/node, @fabricjs/browser, or @fabricjs/node before using environment-dependent APIs, or call setEnv/setEnvFactory.',\n  );\n};\n\nexport const getFabricDocument = (): Document => getEnv().document;\n\nexport const getFabricWindow = (): TFabricWindow => getEnv().window;\n\n/**\n * @returns the config value if defined, fallbacks to the environment value\n */\nexport const getDevicePixelRatio = () =>\n  Math.max(\n    config.devicePixelRatio ?? getFabricWindow().devicePixelRatio ?? 1,\n    1,\n  );\n\nexport type * from './types';","sourceCodeStart":23,"sourceCodeEnd":59,"githubUrl":"https://github.com/fabricjs/fabric.js/blob/2bd4992cabf4ec9609aa349ea09b723cadc94bef/packages/core/src/env/index.ts#L23-L59","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Import a full entry point before using env-dependent APIs: `import { Canvas } from 'fabric'` (browser) or `import { ... } from 'fabric/node'` / `@fabricjs/node` under Node.","For custom/test environments, call `setEnv(yourEnv)` or `setEnvFactory(() => env)` (e.g. jsdom/happy-dom) before any fabric usage.","Check import order: side-effect entry modules must execute before core API calls; avoid importing deep internal paths that bypass the entry point.","In SSR frameworks, guard fabric usage so it only runs on the client (or explicitly set up the node env)."],"exampleFix":"// before\nimport { StaticCanvas } from '@fabricjs/core'; // deep/core-only import\nconst doc = getFabricDocument(); // throws: env not initialized\n\n// after\nimport { StaticCanvas } from 'fabric'; // browser entry sets env\n// or under Node:\n// import { StaticCanvas } from 'fabric/node';\nconst doc = getFabricDocument();","handlingStrategy":"validation","validationCode":"import { getEnv } from 'fabric';\nlet envReady = true;\ntry { getEnv(); } catch { envReady = false; }\nif (!envReady) {\n  // import 'fabric/node' or call setEnvFactory(() => new JSDOM().window)\n}","typeGuard":"const hasEnv = (): boolean => {\n  try { getEnv(); return true; } catch { return false; }\n};","tryCatchPattern":"import { getFabricDocument } from 'fabric';\ntry {\n  const doc = getFabricDocument();\n} catch (e) {\n  if (e instanceof Error && e.message.includes('Fabric env was not initialized')) {\n    // add the correct entry-point import (fabric / fabric/node) or setEnv(), then retry\n  } else throw e;\n}","preventionTips":["Always import from a platform entry point ('fabric' or 'fabric/node'), never deep core-only paths.","In SSR, guard fabric code with a client-only check or set up the node env explicitly.","Set setEnv/setEnvFactory at the top of test setup files before any fabric import executes."],"tags":["fabricjs","environment","ssr","initialization","node"],"backgroundTag":"missing-env-var","analyzedSha":"2bd4992cabf4ec9609aa349ea09b723cadc94bef","analyzedAt":"2026-08-28T10:56:44.286Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}