Edge Function 503 error response

Last edited: 4/1/2026

A 503 HTTP status code from an Edge Function indicates one of three possible events:

  • the function failed to boot due to SyntaxError
  • your own code returned a 503
  • the platform itself is having issues

These require different fixes, so it is useful to decipher the cause before debugging:

Step 1: Figure out which 503 you have#

If you received back a BOOT_ERROR message, like the one below, you can jump to the resolution section: Boot Error

1
{
2
  "code": "BOOT_ERROR",
3
  "message": "Function failed to start (please check logs)"
4
}

Otherwise, run the below query in your Log Explorer.

1
select
2
  req.pathname as function_name,
3
  res.status_code,
4
  case
5
    when metadata.execution_id is not null
6
    and metadata.function_id is not null then 'app_level'
7
    when metadata.execution_id is null
8
    and metadata.function_id is not null then 'boot_error'
9
    when metadata.execution_id is null
10
    and metadata.function_id is null then 'internal_failure'
11
  end as error_type
12
from
13
  function_edge_logs
14
  cross join UNNEST(metadata) as metadata
15
  cross join UNNEST(metadata.request) as req
16
  cross join UNNEST(metadata.response) as res
17
where status_code = 503
18
limit 50;

Depending on the output, you can use this table to find the appropriate debugging section:

ValueGo to
app_levelapp level error
boot_errorboot error - function cannot compile
internal_failureplatform issue

Step 2: Addressing the error#

App level error#

Somewhere in your function logic, you are returning a 503 response yourself:

Example:#

1
return new Response(JSON.stringify(data), {
2
  headers: { ...corsHeaders, 'Content-Type': 'application/json' },
3
  status: 503, // <-- you set this
4
})

Check your function logic and any third-party API responses for where the 503 is originating.

  1. Search your function code for 503. Look for explicit status codes on Response objects
  2. Trace the condition that triggered it. If your function calls external APIs, it may be passing along errors returned by those services
  3. Add logging before the return so future occurrences leave a trace:
1
console.error('Returning 503 - reason:', reason)

See: Error handling in Edge Functions

Boot error#

A SyntaxError prevented your code from dynamically compiling.

In the Function Dashboard, under the affected function's Log tab, you can filter for the key phrase worker boot error:. the log will tell you syntax error occurred:

image

Alternatively, instead of using the Function Dashboard, you can programmatically find boot failure error messages in the Log Explorer with the below query:

1
select
2
  fl.event_message,
3
  content.timestamp,
4
  fel.function_name,
5
  fel.status_code
6
from
7
  function_logs as fl
8
  left join UNNEST(fl.metadata) as content on true
9
  left join (
10
    select
11
      em.function_id,
12
      em.version,
13
      req.pathname as function_name,
14
      res.status_code
15
    from
16
      function_edge_logs
17
      left join UNNEST(metadata) as em on true
18
      left join UNNEST(em.request) as req on true
19
      left join UNNEST(em.response) as res on true
20
  ) as fel
21
    on content.function_id = fel.function_id and content.version = fel.version
22
where content.event_type = 'BootFailure'
23
order by timestamp, function_name
24
limit 20;

Example causes#

Redefining constant variables#

Redefining a constant value can prevent the code from compiling:

redeclaring_values
1
let some_var
2
const some_var // SyntaxError — already declared

The log message for these errors should state the cause already declared and the file impacted.

log_error_message
1
worker boot error: Uncaught SyntaxError:
2
Identifier 'some_var' has already been declared at file:///var/tmp/sb-compile-edge-runtime/source/index.ts:6:7

Key word violations#

Some key words can only be used in specific contexts. For instance, the await key word can only be used inside async functions.

await_in_non_async_function
1
(req: Request) => {
2
  const { name } = await req.json(); // await only works inside async functions
3
}

The log message for these errors should state the cause Unexpected reserved word and the file impacted.

log_error_message
1
worker boot error: Uncaught SyntaxError:
2
Unexpected reserved word at file:///var/tmp/sb-compile-edge-runtime/source/index.ts:6:28

Bad imports: Non-existent modules or named exports#

Imports can cause errors if they're not available within the edge function:

bad_imports
1
// importing non-existent module
2
import supabase from 'does_not_exist'
3
4
// or accessing non-existent export
5
import { doesNotExist } from 'jsr:@supabase/functions-js'
6
7
doesNotExist()

The log message for these errors should state the cause requested module... does not provide an export and the file impacted.

log_error_message
1
worker boot error: Uncaught SyntaxError:
2
The requested module 'jsr:@supabase/functions-js' does not provide an export named 'doesNotExist' at file:///var/tmp/sb-compile-edge-runtime/source/index.ts:2:10”

To fix, check the module and its imports to make sure they exist and are supported by Supabase Edge Functions.

If the module worked before, check to see if the most recent release had breaking changes and then only import the working version.

Platform issue#

The edge function runtime is overwhelmed, or the API Gateway is returning its own 503 due to excessive load.

Open a support ticket and include the relevant log output from Step 1.

Additional resources#

Still stuck?#