Supabase Edge Function BOOT_ERROR: Fix "Failed to Bootstrap"

A Supabase Edge Function that returns:

{"code":"BOOT_ERROR","message":"Worker failed to boot (please check logs)"}

or a log line reading worker boot error: failed to bootstrap runtime: failed to determine entrypoint is failing before a single line of your handler runs. This isn't a runtime exception you can try/catch — the Deno worker never finished loading your function's module graph. That distinction matters because it rules out most application-level debugging and points you at four specific causes.

Cause 1 — an import outside supabase/functions/#

The most common trigger: your function imports a local file that lives outside its own directory tree — for example a shared utils.ts sitting at your project root instead of inside supabase/functions/_shared/. Locally, this is a known limitation of the Edge Runtime's module resolution; in production it fails to build the dependency graph entirely.

Fix: move any shared code into supabase/functions/_shared/ and import with a relative path from there. Don't reach outside the functions/ directory, even for genuinely shared utilities.

Cause 2 — a syntax error or unsupported import Deno rejects#

If the boot log names a specific file and mentions "Unexpected reserved word" or a similar parse error, the module itself has a syntax issue — often from code written for Node.js and pasted in unmodified. Edge Functions run on Deno, not Node.js: require(), Node-only built-ins (fs, path without the node: prefix), and CommonJS-style exports don't resolve the way they do in a Next.js API route.

Fix: run the function through deno check locally before deploying, and confirm every import either uses an npm: or jsr: specifier (Deno's supported ways to pull Node/npm packages) or a Deno-native ESM import — not a bare Node import.

Cause 3 — a Supabase CLI version regression (Windows-specific)#

If imports that worked yesterday suddenly BOOT_ERROR after a routine npm update or CLI upgrade, check your Supabase CLI version — but only if you're on Windows. A confirmed regression (supabase/cli#2862) traces local import failures specifically to CLI v1.187.0+ on Windows, where local file imports resolve incorrectly; the same CLI version works fine on macOS and Linux. If you're not on Windows, skip this cause and keep looking.

Fix (Windows only): pin the CLI to a known-good version (npm install [email protected] --save-dev or the pinned version your team last verified) until the regression is patched, and track supabase/cli#2862 before upgrading again.

Cause 4 — a supabase-js version mismatch inside the function#

If your function itself imports @supabase/supabase-js at "latest" rather than a pinned version, a new release can introduce a boot-time incompatibility with the Edge Runtime's Deno version. Pinning to a specific, verified version (for example @2.49.8 or whatever your team has last confirmed working) removes this as a variable.

How to actually see the real error#

BOOT_ERROR in the client response is deliberately generic — the real cause is always in the logs, not the HTTP response body.

supabase functions deploy my-function --debug

and separately, check Dashboard → Edge Functions → Logs for the exact stack trace and shutdown reason before touching any code. Guessing from the generic BOOT_ERROR message alone wastes more time than reading the log line above it.

Related reading#

• Next.js + Supabase Edge Functions: the complete guide
• Supabase service role key in Next.js — correct usage
• Next.js + Supabase error handling and observability
• Supabase client: permission denied for schema public — fix