Fix guide · updated 2026-11-17
Edge Function 503 BOOT_ERROR "Function failed to start (please check logs)"
{"code":"BOOT_ERROR","message":"Function failed to start (please check logs)"}
Your app calls a Supabase Edge Function and gets status 503 with "Function failed to start (please check logs)", code BOOT_ERROR. Your function never ran: its code couldn't even load, usually because of a mistake in the code or an import that fails. The local server, supabase functions serve, says "Worker failed to boot (please check logs)" for the same thing. We reproduced the usual causes with the Supabase CLI's local function server on Supabase's edge-runtime 1.79.1 and supabase-js 2.119, November 2026.
What your app sees
functions.invoke() returns an error named FunctionsHttpError with the message "Edge Function returned a non-2xx status code". The 503 and the body are inside error.context:
const { data, error } = await supabase.functions.invoke('send-email', { body });
if (error?.context?.status === 503) {
console.log(await error.context.text());
}
On Supabase's servers the body is {"code":"BOOT_ERROR","message":"Function failed to start (please check logs)"}. On your computer, the local server answers {"code":"BOOT_ERROR","message":"Worker failed to boot (please check logs)"}: we got exactly that for all five boot failures below, within a fraction of a second, on every call.
Make sure it's a boot error
Supabase's 503 article lists three kinds of 503 from a function:
- The body says
BOOT_ERROR: the code couldn't load. This guide. - The body is your own, like
{"error":"upstream unavailable"}: your code ran and answered 503 itself, often passing on an outside service's error. Search your function for503. In our test, a function that returned its own 503 came back with its own body, untouched. - Neither: Supabase itself may be having trouble. Check status.supabase.com.
Find the line that broke
In the Supabase dashboard, open the function, then its Logs tab, and search for worker boot error. That line names the problem, and on Supabase's servers it ends with the file and the line number, like this example from Supabase's article:
worker boot error: Uncaught SyntaxError: Identifier 'some_var' has already been declared
at file:///var/tmp/sb-compile-edge-runtime/source/index.ts:6:7
Here, line 6 of the function's index.ts is the culprit. The local server prints the same worker boot error lines in the terminal, so you can see them without deploying.
Cause 1: a mistake in the code
The code isn't valid, so it can't load at all. The two our test reproduced, with the exact log lines:
- A name declared twice, often after pasting a block of code:
worker boot error: Uncaught SyntaxError: Identifier 'some_var' has already been declared. awaitinside a function that isn'tasync, oftenDeno.serve((req) => { … await req.json() … }):worker boot error: Uncaught SyntaxError: Unexpected reserved word. The fix isDeno.serve(async (req) => { … }).
Cause 2: an import that doesn't match
The code imports a name the module doesn't have, or a file that isn't there:
- A named import the module doesn't export, after a rename or a package update:
worker boot error: Uncaught SyntaxError: The requested module './lib.ts' does not provide an export named 'doesNotExist'. - A file that isn't there, because it was renamed, moved, or isn't deployed with the function:
worker boot error: failed to bootstrap runtime: failed to create the graph: Module not found "file:///…/utils/helper.ts". Check the path from the function's own folder.
Cause 3: a package that can't be loaded
Packages imported with npm: or jsr: have to load with the function. The local server downloads them when the function boots: in our test, with no network, the line was worker boot error: failed to bootstrap runtime: failed to create the graph: Failed loading https://registry.npmjs.org/zod for package "zod", followed by the network error. Supabase's article adds the package update that breaks an import: if the package worked before, check its latest release for breaking changes and pin the version that worked, like npm:zod@3.23.8.
Two failures that aren't boot errors
- A check at the top of the file that throws, like
if (!Deno.env.get('STRIPE_SECRET_KEY')) throw new Error(…)outside the handler. In our test, that wasn't a 503: the local server answered 500 with{"code":"WORKER_ERROR","message":"Function exited due to an error (please check logs)"}, and the log saidevent loop error: Error: STRIPE_SECRET_KEY is not set. Add the missing secret, and do such checks inside the handler so they return a clear error. - No
Deno.serve, such as anexport defaulthandler copied from another platform. The function loads fine but never answers. In our test the call waited until the local server's time limit and got a 546: see Edge Function 546 "not having enough compute resources" (WORKER_RESOURCE_LIMIT). Wrap your handler inDeno.serve(handler).
Fix: reproduce it on your computer first
Supabase's own advice for a BOOT_ERROR is to check the logs and run the function locally with supabase functions serve. Call it once: if it can't boot, the terminal shows the same worker boot error line right away, and you can fix and retry in seconds instead of deploying each guess.
The local server doesn't add the sb-error-code header to these answers, as we saw in its source and its answers, so in your app check the status and the body's code, not the header.
If an AI tool built your app
Give your AI tool this prompt, with the log line from your function:
My Supabase Edge Function "send-email" fails with 503 BOOT_ERROR ("Function failed to start (please check logs)"). The function's log says: [paste the full "worker boot error" line here]. Fix the line or import it names: a name declared twice, await outside an async function (Deno.serve must get an async handler), a named import the module doesn't export, an import path that doesn't exist from the function's folder, or an npm:/jsr: package version that doesn't exist or doesn't run in Deno. Keep secret checks inside the handler, and make sure the file calls Deno.serve. Show me each change before making it.
Not quite your error?
- Another status, such as 401 or 500: Edge Function returned a non-2xx status code: read the real error and fix it.
- 546, "not having enough compute resources": Edge Function 546 "not having enough compute resources" (WORKER_RESOURCE_LIMIT).
- The browser blocks the call with a CORS error: Supabase Edge Function "blocked by CORS policy": every message, fixed.
Still stuck?
Undo the function's last change and deploy again. If it boots, the error is in what you changed: add it back piece by piece until the 503 returns.
Other Supabase problems? See Supabase fixes.