mirror of
https://github.com/supabase/supabase.git
synced 2026-10-05 09:25:06 +03:00
docs: adding 503 troubleshooting guide (#44255)
## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? docs update ## What is the new behavior? Adds 503 troubleshooting doc <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Added comprehensive troubleshooting guide for Edge Function 503 error responses, including diagnostic procedures to classify errors into three categories (app-level, boot-level, and internal failures) with detailed resolution instructions specific to each error type and links to complementary resources. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Chris Chinchilla <chris.ward@supabase.io>
This commit is contained in:
TheOtherBrian1andChris Chinchilla authored and GitHub committed
1 parent
908da85225
commit
977d25c66d
2 files changed
+203
No files matched your search
@@ -0,0 +1,203 @@
|
||||
---
|
||||
title = "Edge Function 503 error response"
|
||||
topics = [ "functions" ]
|
||||
keywords = [ "503", "error" ]
|
||||
|
||||
[[errors]]
|
||||
http_status_code = 503
|
||||
code = "BOOT_ERROR"
|
||||
message = "Function failed to start (please check logs)"
|
||||
---
|
||||
|
||||
A 503 HTTP status code from an Edge Function indicates one of three possible events:
|
||||
|
||||
- the function failed to boot due to [`SyntaxError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](#boot-error)
|
||||
|
||||
```json
|
||||
{
|
||||
"code": "BOOT_ERROR",
|
||||
"message": "Function failed to start (please check logs)"
|
||||
}
|
||||
```
|
||||
|
||||
Otherwise, run the below query in your [Log Explorer](/dashboard/project/_/logs/explorer?q=SELECT%0A++++req.pathname+AS+function_name%2C%0A++++res.status_code%2C%0A++++CASE%0A++++++++WHEN+metadata.execution_id+IS+NOT+NULL+AND+metadata.function_id+IS+NOT+NULL+THEN+%27app_level%27%0A++++++++WHEN+metadata.execution_id+IS+NULL+++++AND+metadata.function_id+IS+NOT+NULL+THEN+%27boot_error%27%0A++++++++WHEN+metadata.execution_id+IS+NULL+++++AND+metadata.function_id+IS+NULL+++++THEN+%27internal_failure%27%0A++++END+AS+error_type%0AFROM+function_edge_logs%0ACROSS+JOIN+UNNEST%28metadata%29+AS+metadata+%0ACROSS+JOIN+UNNEST%28metadata.request%29+AS+req+%0ACROSS+JOIN+UNNEST%28metadata.response%29+AS+res+%0AWHERE+%0A++++status_code+%3D+503+%0ALIMIT+50%3B).
|
||||
|
||||
```sql
|
||||
select
|
||||
req.pathname as function_name,
|
||||
res.status_code,
|
||||
case
|
||||
when metadata.execution_id is not null
|
||||
and metadata.function_id is not null then 'app_level'
|
||||
when metadata.execution_id is null
|
||||
and metadata.function_id is not null then 'boot_error'
|
||||
when metadata.execution_id is null
|
||||
and metadata.function_id is null then 'internal_failure'
|
||||
end as error_type
|
||||
from
|
||||
function_edge_logs
|
||||
cross join UNNEST(metadata) as metadata
|
||||
cross join UNNEST(metadata.request) as req
|
||||
cross join UNNEST(metadata.response) as res
|
||||
where status_code = 503
|
||||
limit 50;
|
||||
```
|
||||
|
||||
Depending on the output, you can use this table to find the appropriate debugging section:
|
||||
|
||||
| Value | Go to |
|
||||
| ------------------ | --------------------------------------------------- |
|
||||
| `app_level` | [app level error](#app-level-error) |
|
||||
| `boot_error` | [boot error - function cannot compile](#boot-error) |
|
||||
| `internal_failure` | [platform issue](#platformissue) |
|
||||
|
||||
## Step 2: Addressing the error
|
||||
|
||||
## App level error
|
||||
|
||||
Somewhere in your function logic, you are returning a 503 response yourself:
|
||||
|
||||
### Example:
|
||||
|
||||
```js
|
||||
return new Response(JSON.stringify(data), {
|
||||
headers: { ...corsHeaders, 'Content-Type': 'application/json' },
|
||||
status: 503, // <-- you set this
|
||||
})
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```js
|
||||
console.error('Returning 503 - reason:', reason)
|
||||
```
|
||||
|
||||
See: [Error handling in Edge Functions](/docs/guides/functions/error-handling)
|
||||
|
||||
## Boot error
|
||||
|
||||
A [`SyntaxError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SyntaxError) prevented your code from dynamically compiling.
|
||||
|
||||
In the [Function Dashboard](/dashboard/project/_/functions), 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:
|
||||
|
||||
|
||||
|
||||
Alternatively, instead of using the Function Dashboard, you can programmatically find boot failure error messages in the [Log Explorer](</dashboard/project/_/logs/explorer?q=SELECT%0A++fl.event_message,%0A++content.timestamp,%0A++fel.function_name,%0A++fel.status_code%0AFROM+function_logs+fl%0ALEFT+JOIN+UNNEST(fl.metadata)+AS+content+ON+TRUE%0ALEFT+JOIN+(%0A++SELECT%0A++++em.function_id,%0A++++em.version,%0A++++req.pathname+AS+function_name,%0A++++res.status_code%0A++FROM+function_edge_logs%0A++LEFT+JOIN+UNNEST(metadata)+AS+em+ON+TRUE%0A++LEFT+JOIN+UNNEST(em.request)+AS+req+ON+TRUE%0A++LEFT+JOIN+UNNEST(em.response)+AS+res+ON+TRUE%0A)+fel+ON+content.function_id+=+fel.function_id%0A++AND+content.version+=+fel.version%0AWHERE+%0A++content.event_type+=+%27BootFailure%27%0AORDER+BY+timestamp,+function_name%0ALIMIT+20;&its=&ite=>) with the below query:
|
||||
|
||||
```sql
|
||||
select
|
||||
fl.event_message,
|
||||
content.timestamp,
|
||||
fel.function_name,
|
||||
fel.status_code
|
||||
from
|
||||
function_logs as fl
|
||||
left join UNNEST(fl.metadata) as content on true
|
||||
left join (
|
||||
select
|
||||
em.function_id,
|
||||
em.version,
|
||||
req.pathname as function_name,
|
||||
res.status_code
|
||||
from
|
||||
function_edge_logs
|
||||
left join UNNEST(metadata) as em on true
|
||||
left join UNNEST(em.request) as req on true
|
||||
left join UNNEST(em.response) as res on true
|
||||
) as fel
|
||||
on content.function_id = fel.function_id and content.version = fel.version
|
||||
where content.event_type = 'BootFailure'
|
||||
order by timestamp, function_name
|
||||
limit 20;
|
||||
```
|
||||
|
||||
### Example causes
|
||||
|
||||
### Redefining constant variables
|
||||
|
||||
Redefining a constant value can prevent the code from compiling:
|
||||
|
||||
```js name=redeclaring_values
|
||||
let some_var
|
||||
const some_var // SyntaxError — already declared
|
||||
```
|
||||
|
||||
The log message for these errors should state the cause `already declared` and the file impacted.
|
||||
|
||||
```sh name=log_error_message
|
||||
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
|
||||
```
|
||||
|
||||
### 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.
|
||||
|
||||
```js name=await_in_non_async_function
|
||||
(req: Request) => {
|
||||
const { name } = await req.json(); // await only works inside async functions
|
||||
}
|
||||
```
|
||||
|
||||
The log message for these errors should state the cause `Unexpected reserved word` and the file impacted.
|
||||
|
||||
```sh name=log_error_message
|
||||
worker boot error: Uncaught SyntaxError:
|
||||
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:
|
||||
|
||||
```js name=bad_imports
|
||||
// importing non-existent module
|
||||
import supabase from 'does_not_exist'
|
||||
|
||||
// or accessing non-existent export
|
||||
import { doesNotExist } from 'jsr:@supabase/functions-js'
|
||||
|
||||
doesNotExist()
|
||||
```
|
||||
|
||||
The log message for these errors should state the cause `requested module... does not provide an export` and the file impacted.
|
||||
|
||||
```sh name=log_error_message
|
||||
worker boot error: Uncaught SyntaxError:
|
||||
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](/dashboard/support/new) and include the relevant log output from Step 1.
|
||||
|
||||
## Additional resources
|
||||
|
||||
- [Logging Edge Function Requests](/docs/guides/functions/logging)
|
||||
- [Error Handling Edge Functions](/docs/guides/functions/error-handling)
|
||||
- [Local Debugging with Chrome Dev Tools](/docs/guides/functions/debugging-tools)
|
||||
- [Quickstart Deployment: Dashboard](/docs/guides/functions/quickstart-dashboard)
|
||||
- [Quickstart Deployment: CLI](/docs/guides/functions/quickstart)
|
||||
|
||||
## Still stuck?
|
||||
|
||||
- Check the [Discord](https://discord.com/channels/839993398554656828/1006358244786196510), [Supabase GitHub Discussions](https://github.com/orgs/supabase/discussions), and [Reddit page](https://www.reddit.com/r/Supabase/) for similar reports that can help with debugging
|
||||
- Open a [support ticket](/dashboard/support/new) for your project if the problem persists and you believe it is a platform issue
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 49 KiB |
Reference in new issue
Block a user