mirror of
https://github.com/supabase/supabase.git
synced 2026-10-05 09:25:06 +03:00
Ali WaseemandJordi Enric
01d12e83c1
The 47 BigQuery-era logs queries across these 20 pages error on the
ClickHouse-backed logs engine ("Backend error! Retry your query."). This
converts them per the rules in `apps/studio/lib/ai/clickhouse-logs.ts`
and repoints every Logs Explorer link at the SQL Editor with the query
source set to **Logs**, since the Logs Explorer is being retired. Also
fixes two stale PostgreSQL 12 links in the tables guide.
Each of the 14 prefilled links was verified to decode back to exactly
the SQL shown on its page. One caveat for review:
`response.headers.proxy_status` in `postgrest-error-codes.mdx` is
unverified — it isn't in the published field reference, and the test
project had no `edge_logs` traffic to confirm against.
Fixes DOCS-1331
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **Documentation**
- Updated database, storage, API, and Edge Function logging guides to
use the SQL Editor and current Logs interface.
- Replaced legacy Log Explorer and BigQuery examples with current query
syntax and structured log fields.
- Refreshed troubleshooting queries for error diagnosis, filtering,
aggregation, and performance analysis.
- Improved examples with clearer source filters, status handling,
request details, joins, and result limits.
- Updated PostgreSQL documentation links and clarified how API error
codes appear in responses.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Jordi Enric <jordi.err@gmail.com>
204 lines
9.3 KiB
Plaintext
204 lines
9.3 KiB
Plaintext
---
|
|
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 the [SQL Editor](/dashboard/project/_/sql/new?skip=true&source=logs&content=select%0A%20%20log_attributes%5B%27request.pathname%27%5D%20as%20function_name%2C%0A%20%20log_attributes%5B%27response.status_code%27%5D%20as%20status_code%2C%0A%20%20case%0A%20%20%20%20when%20log_attributes%5B%27execution_id%27%5D%20%21%3D%20%27%27%0A%20%20%20%20and%20log_attributes%5B%27function_id%27%5D%20%21%3D%20%27%27%20then%20%27app_level%27%0A%20%20%20%20when%20log_attributes%5B%27execution_id%27%5D%20%3D%20%27%27%0A%20%20%20%20and%20log_attributes%5B%27function_id%27%5D%20%21%3D%20%27%27%20then%20%27boot_error%27%0A%20%20%20%20when%20log_attributes%5B%27execution_id%27%5D%20%3D%20%27%27%0A%20%20%20%20and%20log_attributes%5B%27function_id%27%5D%20%3D%20%27%27%20then%20%27internal_failure%27%0A%20%20end%20as%20error_type%0Afrom%20logs%0Awhere%0A%20%20source%20%3D%20%27function_edge_logs%27%0A%20%20and%20toInt32OrZero%28log_attributes%5B%27response.status_code%27%5D%29%20%3D%20503%0Alimit%2050%3B).
|
|
|
|
```sql
|
|
select
|
|
log_attributes['request.pathname'] as function_name,
|
|
log_attributes['response.status_code'] as status_code,
|
|
case
|
|
when log_attributes['execution_id'] != ''
|
|
and log_attributes['function_id'] != '' then 'app_level'
|
|
when log_attributes['execution_id'] = ''
|
|
and log_attributes['function_id'] != '' then 'boot_error'
|
|
when log_attributes['execution_id'] = ''
|
|
and log_attributes['function_id'] = '' then 'internal_failure'
|
|
end as error_type
|
|
from logs
|
|
where
|
|
source = 'function_edge_logs'
|
|
and toInt32OrZero(log_attributes['response.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 [SQL Editor](/dashboard/project/_/sql/new?skip=true&source=logs&content=select%0A%20%20fl.event_message%2C%0A%20%20fl.timestamp%2C%0A%20%20fel.function_name%2C%0A%20%20fel.status_code%0Afrom%0A%20%20%28%0A%20%20%20%20select%0A%20%20%20%20%20%20timestamp%2C%0A%20%20%20%20%20%20event_message%2C%0A%20%20%20%20%20%20log_attributes%5B%27function_id%27%5D%20as%20function_id%2C%0A%20%20%20%20%20%20log_attributes%5B%27version%27%5D%20as%20version%0A%20%20%20%20from%20logs%0A%20%20%20%20where%20source%20%3D%20%27function_logs%27%0A%20%20%20%20%20%20and%20log_attributes%5B%27event_type%27%5D%20%3D%20%27BootFailure%27%0A%20%20%29%20as%20fl%0A%20%20left%20join%20%28%0A%20%20%20%20select%0A%20%20%20%20%20%20log_attributes%5B%27function_id%27%5D%20as%20function_id%2C%0A%20%20%20%20%20%20log_attributes%5B%27version%27%5D%20as%20version%2C%0A%20%20%20%20%20%20log_attributes%5B%27request.pathname%27%5D%20as%20function_name%2C%0A%20%20%20%20%20%20log_attributes%5B%27response.status_code%27%5D%20as%20status_code%0A%20%20%20%20from%20logs%0A%20%20%20%20where%20source%20%3D%20%27function_edge_logs%27%0A%20%20%29%20as%20fel%20on%20fl.function_id%20%3D%20fel.function_id%20and%20fl.version%20%3D%20fel.version%0Aorder%20by%20fl.timestamp%2C%20fel.function_name%0Alimit%2020%3B) with the below query:
|
|
|
|
```sql
|
|
select
|
|
fl.event_message,
|
|
fl.timestamp,
|
|
fel.function_name,
|
|
fel.status_code
|
|
from
|
|
(
|
|
select
|
|
timestamp,
|
|
event_message,
|
|
log_attributes['function_id'] as function_id,
|
|
log_attributes['version'] as version
|
|
from logs
|
|
where source = 'function_logs'
|
|
and log_attributes['event_type'] = 'BootFailure'
|
|
) as fl
|
|
left join (
|
|
select
|
|
log_attributes['function_id'] as function_id,
|
|
log_attributes['version'] as version,
|
|
log_attributes['request.pathname'] as function_name,
|
|
log_attributes['response.status_code'] as status_code
|
|
from logs
|
|
where source = 'function_edge_logs'
|
|
) as fel on fl.function_id = fel.function_id and fl.version = fel.version
|
|
order by fl.timestamp, fel.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
|