The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
TypeScript aialternativeauthdatabasedenoembeddingsexamplefirebasenextjsoauth2pgvectorpostgispostgrespostgresqlpostgrestrealtimesupabasevectorswebsockets
docs(functions): add error codes page (#46833)
Kalleby Santose5832d210c3b
diff --git a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.tsindex ee15f6ff838..ed67342631d 100644--- a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts+++ b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts@@ -1744,6 +1744,10 @@ export const functions: NavMenuConstant = {name: 'Status codes',url: '/guides/functions/status-codes' as `/${string}`,},+ {+ name: 'Error codes',+ url: '/guides/functions/error-codes' as `/${string}`,+ },{name: 'Recursive/Nested function calls',url: '/guides/functions/recursive-functions' as `/${string}`,diff --git a/apps/docs/content/guides/functions/error-codes.mdx b/apps/docs/content/guides/functions/error-codes.mdxnew file mode 100644index 00000000000..cd9e1a4bb5d--- /dev/null+++ b/apps/docs/content/guides/functions/error-codes.mdx@@ -0,0 +1,304 @@+---+id: 'functions-error-codes'+title: 'Error codes'+description: 'Edge Functions can return the following error codes.'+subtitle: 'Understand the error codes returned by Edge Functions to properly debug issues and handle responses.'+---++{/* supa-mdx-lint-disable Rule001HeadingCase */}++When an Edge Function request fails, the response includes a `sb-error-code` header that identifies the specific error.+You can inspect this header in your HTTP client or application code to detect and handle errors programmatically.++```js+const response = await fetch('<your-function-url>')++if (!response.ok) {+ const errorCode = response.headers.get('sb-error-code')+ console.error('Edge Function error:', errorCode)+}+```++## Bad Implementation Errors++These errors are caused by issues in your function's code or logic which requires updating its implementation.++### EDGE_FUNCTION_ERROR++**Cause:** Your Edge Function is throwing an unhandled error or resulting a 5XX code.++```ts+// ...++function process() {+ throw new Error('Some unhandled error')+}++export default {+ fetch: withSupabase({ auth: 'none' }, async () => {+ process()++ return new Response()+ }),+}+```++**Solution:**++- Ensure you are catching errors in your code logic with try-catch blocks.++```ts+function process() {+ throw new Error('Some unhandled error')+}++// ...++try {+ process()+ return new Response()+} catch (e) {+ console.error('Process fail:', e)+ return new Response(null, { status: 500 })+}+```++### IDLE_TIMEOUT++**Cause:** Your Edge Function did not respond within the [request timeout limit](/docs/guides/functions/limits).++**Common causes:**++- Long-running database queries+- Slow external API calls+- Infinite loops or blocking operations++**Solution:**++- Optimize slow operations+- Add timeout handling to external requests+- Consider breaking large operations into smaller chunks++### WORKER_RESOURCE_LIMIT, WORKER_LIMIT++**Cause:** Your Edge Function execution was stopped due to exceeding resource limits. Edge Function logs should indicate which [resource limit](/docs/guides/functions/limits) was exceeded.++**Common causes:**++- Memory usage exceeded available limits+- CPU time exceeded execution quotas+- Too many concurrent operations++**Solution:** Check your Edge Function logs to see which resource limit was exceeded, then optimize your function accordingly.++### WORKER_ERROR++**Cause:** Your Edge Function threw an uncaught exception.++```ts+// ...++function initSomething() {+ throw new Error('Some unhandled error')+}++initSomething() // Error threw outside request handler++export default {+ fetch: withSupabase({ auth: 'none' }, async () => {+ return new Response()+ }),+}+```++**Common causes:**++- Unhandled JavaScript errors in your function code, outside request handler+- Missing error handling for async operations+- Invalid JSON parsing++**Solution:** Check your Edge Function logs to identify the specific error and add proper error handling to your code.++### INVALID_RESPONSE_STATUS_CODE++**Cause:** Your Edge Function is returning an invalid HTTP status code — not equal to `101` and outside the range `[200, 599]`++**Common causes:**++- Proxying an external service that returns an invalid HTTP status code++```ts+// ...++export default {+ fetch: withSupabase({ auth: 'none' }, async (req) => {+ // Fails in case this proxied server return a status >599+ return fetch('https://some-server-to-proxy', {+ method: req.method,+ headers: req.headers,+ body: req.body,+ })+ }),+}+```++**Solution:**++- Ensure you are returning a valid HTTP status code+- For proxy endpoints, do not return the `fetch()` result directly; instead return a new `Response` wrapped in a try-catch block++```ts+// ...++export default {+ fetch: withSupabase({ auth: 'none' }, async (req) => {+ try {+ const res = await fetch('https://some-server-to-proxy', {+ method: req.method,+ headers: req.headers,+ body: req.body,+ })++ // Creating a 'new Response()' ensures contructor checks+ return new Response(await res.body, {+ headers: res.headers,+ status: res.status,+ statusText: res.statusText,+ })+ } catch (e) {+ console.error('Proxy Error', e)+ return new Response(null, { status: 502 })+ }+ }),+}+```++## Authentication Errors++These errors occur when the request contains a missing, malformed, or unsupported JWT token. Fixing them requires ensuring your requests include a valid authorization header, or disabling JWT verification for public endpoints.+For further information, see [Authorization headers](/docs/guides/functions/auth-headers) and [Securing Edge Functions](/guides/functions/auth).++### UNAUTHORIZED_NO_AUTH_HEADER++**Cause:** The Edge Function has JWT verification enabled, but the request is missing the `Authorization` or `apikey` header.++**Solution:**++- Ensure you are passing a valid JWT token in the `Authorization` header+- Check that you are sending an API key in the `apikey` header+- For webhooks or public endpoints, consider disabling JWT verification++### UNAUTHORIZED_ASYMMETRIC_JWT++**Cause:** The Edge Function has JWT verification enabled, but the `Authorization` header contains an invalid asymmetric `ES256 | RS256` token.++**Solution:**++- Ensure you are passing a valid user JWT token in the `Authorization` header+- Check that your token has not expired++### UNAUTHORIZED_LEGACY_JWT++**Cause:** The Edge Function has JWT verification enabled, but the `Authorization` header contains an invalid legacy `HS256` token.++**Solution:**++- Ensure you are passing a valid legacy JWT token in the `Authorization` header+- Check that your token has not expired+- Verify that the legacy JWT secret has not been revoked or disabled++### UNAUTHORIZED_UNSUPPORTED_TOKEN_ALGORITHM++**Cause:** The Edge Function has JWT verification enabled, but the `Authorization` header does not contain an `ES256 | RS256 | HS256` token.++**Solution:**++- Ensure you are passing a valid Supabase-issued JWT token in the `Authorization` header++### UNAUTHORIZED_INVALID_JWT_FORMAT++**Cause:** The Edge Function has JWT verification enabled, but the `Authorization` header does not follow the `Bearer <JWT Token>` format.++**Solution:**++- Check that you are passing `Bearer <JWT Token>` in the `Authorization` header+- Ensure you are sending an API key in the `apikey` header instead of `Authorization`+- For webhooks or public endpoints, consider disabling JWT verification++## Request Errors++These errors indicate issues with the request itself, which typically require changing how the function is called.++### RATE_LIMIT_EXCEEDED++**Cause:** The platform detected [recursive or nested function call](/docs/guides/functions/recursive-functions) behavior.++**Common causes:**++- Multiple function-to-function calls+- Recursive or circular calls++**Solution:**++- Use the suggested retry window in seconds from the error message before calling your function again+- Ensure you are not performing unnecessary individual calls; use batch operations where possible+- Delegate large workloads to queues instead of recursively calling other Edge Functions++### INVALID_URL++**Cause:** The platform rejected a malformed URL.++**Solution:**++- Ensure you are calling with a valid [formatted URL](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL)++---++## Server Errors++These errors indicate issues with function loading, execution, or the underlying platform.++### NOT_FOUND++**Cause:** The Edge Function metadata or files were not found or are missing in the specific region.++**Solution:** Try redeploying your function and wait a few minutes to make sure all regions have been updated.++### BOOT_ERROR++**Cause:** Your Edge Function failed to start.++**Common causes:**++- Syntax errors preventing the function from loading+- Import errors or missing dependencies+- Invalid function configuration++**Solution:** Check your Edge Function logs and also verify that your function code can be executed locally with `supabase functions serve`.++### LOAD_FUNCTION_ERROR++**Cause:** The platform was unable to load your function metadata or files.++**Solution:**++- Try calling your function again after a short delay+- If the problem persists, contact support++### LOAD_FUNCTION_METADATA_ERROR++**Cause:** The platform could not fetch your function metadata, possibly due to external cache issues.++**Solution:**++- Wait a few minutes before calling your function again+- If the problem persists, contact support++### LOAD_FUNCTION_INVALID_ENTRYPOINT_PATH_ERROR++**Cause:** Your Edge Function metadata is broken or contains an invalid entrypoint.++**Solution:**++- Try redeploying your function+- If the problem persists, contact support