apps/docs/content/guides/functions/error-codes.mdx
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.
const response = await fetch('<your-function-url>')
if (!response.ok) {
const errorCode = response.headers.get('sb-error-code')
console.error('Edge Function error:', errorCode)
}
These errors are caused by issues in your function's code or logic which requires updating its implementation.
Cause: Your Edge Function is throwing an unhandled error or resulting a 5XX code.
// ...
function process() {
throw new Error('Some unhandled error')
}
export default {
fetch: withSupabase({ auth: 'none' }, async () => {
process()
return new Response()
}),
}
Solution:
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 })
}
Cause: Your Edge Function did not respond within the request timeout limit.
Common causes:
Solution:
Cause: Your Edge Function execution was stopped due to exceeding resource limits. Edge Function logs should indicate which resource limit was exceeded.
Common causes:
Solution: Check your Edge Function logs to see which resource limit was exceeded, then optimize your function accordingly.
Cause: Your Edge Function threw an uncaught exception.
// ...
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:
Solution: Check your Edge Function logs to identify the specific error and add proper error handling to your code.
Cause: Your Edge Function is returning an invalid HTTP status code — not equal to 101 and outside the range [200, 599]
Common causes:
// ...
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:
fetch() result directly; instead return a new Response wrapped in a try-catch block// ...
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 })
}
}),
}
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 and Securing Edge Functions.
Cause: The Edge Function has JWT verification enabled, but the request is missing the Authorization or apikey header.
Solution:
Authorization headerapikey headerCause: The Edge Function has JWT verification enabled, but the Authorization header contains an invalid asymmetric ES256 | RS256 token.
Solution:
Authorization headerCause: The Edge Function has JWT verification enabled, but the Authorization header contains an invalid legacy HS256 token.
Solution:
Authorization headerCause: The Edge Function has JWT verification enabled, but the Authorization header does not contain an ES256 | RS256 | HS256 token.
Solution:
Authorization headerCause: The Edge Function has JWT verification enabled, but the Authorization header does not follow the Bearer <JWT Token> format.
Solution:
Bearer <JWT Token> in the Authorization headerapikey header instead of AuthorizationThese errors indicate issues with the request itself, which typically require changing how the function is called.
Cause: The platform detected recursive or nested function call behavior.
Common causes:
Solution:
Cause: The platform rejected a malformed URL.
Solution:
These errors indicate issues with function loading, execution, or the underlying platform.
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.
Cause: Your Edge Function metadata resolved, but its deployment bundle was missing from storage and could not be loaded (the metadata points at a different version than the stored bundle). This returns the same Requested function was not found message as NOT_FOUND, so the sb-error-code header is what distinguishes them — see Edge Function 404 error response.
Common causes:
/deploy?bundleOnly=true where the bulk metadata update failedSolution:
Cause: Your Edge Function failed to start.
Common causes:
Solution: Check your Edge Function logs and also verify that your function code can be executed locally with supabase functions serve.
Cause: The platform was unable to load your function metadata or files.
Solution:
Cause: The platform could not fetch your function metadata, possibly due to external cache issues.
Solution:
Cause: Your Edge Function metadata is broken or contains an invalid entrypoint.
Solution:
Cause: Your Edge Function deployment bundle was fetched, but could not be unbundled because decompressing or parsing it failed. This usually means the bundle is corrupt or was only partially written.
Solution: