App Finishers

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:

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:

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:

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

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?

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.