Troubleshoot embedding and builds

Use this page when an embedded Excalidraw instance fails to render, a build fails, or text appears incorrect. The checks are ordered from the least invasive layout and browser checks to targeted build fixes; collect errors without publishing secrets.

Before you begin

Confirm the package version, framework, bundler, browser console error, and smallest component code that reproduces the problem. Test in a non-production environment and keep scene data out of logs.

The editor has no visible size

Symptom: The component mounts but the canvas is blank or has no usable area.

Cause: Excalidraw uses 100% of the containing block's width and height. A parent with no non-zero dimensions gives the editor no visible area.

Fix: Give the containing block an explicit or inherited width and height:

.editor-shell {
  width: 100%;
  height: 600px;
}

Verify: Inspect computed dimensions and confirm both are greater than zero. The canvas should occupy that area.

The worker URL error appears

Symptom: The console reports WorkerUrlNotDefinedError.

Cause: The worker pool was created without a worker URL; the source throws this error when the URL is undefined.

Fix: Follow the supported package and bundler setup for your installed version and ensure worker assets are emitted with a URL passed through supported configuration. Do not hide the exception or inline the worker into the main chunk.

Verify: Rebuild the host app and confirm the error no longer appears when the worker-backed feature is used.

The worker is bundled into the main chunk

Symptom: The console reports that worker code was bundled into the main chunk.

Cause: Worker creation rejects a worker URL that resolves to the main module URL.

Fix: Configure the bundler to emit the worker as a separate asset and preserve the URL reference used by the package. Inspect the production bundle as well as development behavior.

Verify: The worker has its own emitted asset and the feature responds without the main-chunk error.

Server rendering fails

Symptom: An SSR or server build fails while importing or rendering the editor.

Cause: Excalidraw depends on browser APIs and browser-side rendering. Next.js integration requires a client boundary and dynamic-import handling.

Fix: Render the editor from a client boundary and use the framework's documented dynamic-import pattern with server-side rendering disabled for the editor component. Keep browser-only access in the client-rendered path.

Verify: The server build completes and the editor renders after client hydration.

The build reports a missing process value

Symptom: Vite reports ReferenceError: process is not defined.

Cause: The package reads process.env.IS_PREACT, while Vite removes environment variables by default.

Fix: Define the value in Vite configuration:

define: {
  "process.env.IS_PREACT": JSON.stringify("true"),
},

Use the value required by your selected build rather than copying a setting without understanding the target.

Verify: Restart the build and confirm the missing-process error is gone.

Text elements have incorrect dimensions

Symptom: Text is missing, clipped, or measured incorrectly, especially in Brave.

Cause: Brave's Aggressive Anti-Fingerprinting setting can break the measureText API used for text elements.

Fix: For the affected test profile, open Brave Shield controls and change Aggressively Block Fingerprinting to Block Fingerprinting. Apply this only to the browser profile used for the test.

Verify: Reload the editor and inspect a text element. If it still renders incorrectly, capture the browser, package version, and console error for an issue or discussion.

Next steps

Use the framework integration guide, then review Excalidraw component props and configuration. For collaboration behavior, see Collaboration and sharing integration reference.