Supabase · Edge Functions · all subjects

error handling & logging

17 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

sb-error-code header for error detection

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. Example: `const errorCode = response.headers.get('sb-error-code')`.

EDGE_FUNCTION_ERROR cause and solution

The EDGE_FUNCTION_ERROR occurs when your Edge Function is throwing an unhandled error or resulting in a 5XX code. Solution: Ensure you are catching errors in your code logic with try-catch blocks to prevent unhandled errors from bubbling up.

IDLE_TIMEOUT error in Edge Functions

The IDLE_TIMEOUT error occurs when your Edge Function did not respond within the request timeout limit. Common causes include long-running database queries, slow external API calls, and infinite loops or blocking operations. Solutions: optimize slow operations, add timeout handling to external requests, and consider breaking large operations into smaller chunks.

WORKER_RESOURCE_LIMIT and WORKER_LIMIT errors

The WORKER_RESOURCE_LIMIT and WORKER_LIMIT errors occur when your Edge Function execution was stopped due to exceeding resource limits. Common causes include memory usage exceeding available limits, CPU time exceeding execution quotas, and too many concurrent operations. Solution: Check your Edge Function logs to identify which resource limit was exceeded, then optimize your function accordingly.

WORKER_ERROR cause and solution

The WORKER_ERROR occurs when your Edge Function threw an uncaught exception, typically outside the request handler. Common causes include unhandled JavaScript errors in function code, missing error handling for async operations, and 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 error

The INVALID_RESPONSE_STATUS_CODE error occurs when your Edge Function is returning an invalid HTTP status code — not equal to 101 and outside the range [200, 599]. Solution: Ensure you are returning a valid HTTP status code. For proxy endpoints, do not return the fetch() result directly; instead wrap the response in a new Response() with a try-catch block to ensure proper status code validation.

RATE_LIMIT_EXCEEDED error for recursive function calls

The RATE_LIMIT_EXCEEDED error occurs when the platform detects recursive or nested function call behavior, typically caused by multiple function-to-function calls or circular calls. Solution: Use the suggested retry window in seconds from the error message before calling your function again, avoid unnecessary individual calls by using batch operations, and delegate large workloads to queues instead of recursively calling other Edge Functions.

INVALID_URL error

The INVALID_URL error occurs when the platform rejected a malformed URL. Solution: Ensure you are calling with a valid formatted URL according to the URL standard.

NOT_FOUND error for Edge Functions

The NOT_FOUND error occurs when 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.

NOT_FOUND_FUNCTION_BLOB error

The NOT_FOUND_FUNCTION_BLOB error occurs when 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, but the sb-error-code header distinguishes them. Common causes include concurrent deploys of the same function running concurrently or a batch deploy using /deploy?bundleOnly=true where the bulk metadata update failed. Solution: Redeploy your function with the latest version of the Supabase CLI, avoid running concurrent deploys of the same function, or contact support if the problem persists.

BOOT_ERROR in Edge Functions

The BOOT_ERROR occurs when your Edge Function failed to start. Common causes include syntax errors preventing the function from loading, import errors or missing dependencies, and invalid function configuration. Solution: Check your Edge Function logs and verify that your function code can be executed locally with `supabase functions serve`.

LOAD_FUNCTION_METADATA_ERROR cause and solution

The LOAD_FUNCTION_METADATA_ERROR occurs when the platform could not fetch your function metadata, possibly due to external cache issues. Solution: Wait a few minutes before calling your function again, or contact support if the problem persists.

LOAD_FUNCTION_INVALID_ENTRYPOINT_PATH_ERROR cause and solution

The LOAD_FUNCTION_INVALID_ENTRYPOINT_PATH_ERROR occurs when your Edge Function metadata is broken or contains an invalid entrypoint. Solution: Try redeploying your function or contact support if the problem persists.

LOAD_FUNCTION_UNBUNDLING_ERROR cause and solution

The LOAD_FUNCTION_UNBUNDLING_ERROR occurs when your Edge Function deployment bundle was fetched but could not be unbundled because decompressing or parsing it failed, usually meaning the bundle is corrupt or was only partially written. Solution: Try redeploying your function or contact support if the problem persists.

Example code for detecting and handling sb-error-code header

const response = await fetch('<your-function-url>') if (!response.ok) { const errorCode = response.headers.get('sb-error-code') console.error('Edge Function error:', errorCode) }

Example of error handling with try-catch in Edge Function

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 }) }

Example of proper proxy error handling in Edge Functions

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 constructor 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 }) } }), }

Give your agent this brain