From b97ad08be568ac68a0aadbdbb7775173d858c7b1 Mon Sep 17 00:00:00 2001 From: "claude[bot]" <209825114+claude[bot]@users.noreply.github.com> Date: Wed, 5 Aug 2026 14:05:03 -0600 Subject: [PATCH] docs: updating Edge Functions error codes (#48767) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit _Requested by **Kalleby Santos** · [Slack thread](https://supabase.slack.com/archives/C02KMRX22NR/p1785949561216739?thread_ts=1785949561.216739&cid=C02KMRX22NR)_ ## 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. Adds two missing entries to the Edge Functions **Error codes** page (`apps/docs/content/guides/functions/error-codes.mdx`). Refs https://github.com/supabase/supabase/issues/47739 ## What is the current behavior? Neither `NOT_FOUND_FUNCTION_BLOB` nor `LOAD_FUNCTION_UNBUNDLING_ERROR` appears on the Error codes page. Someone who gets a 404 with `sb-error-code: NOT_FOUND_FUNCTION_BLOB` and searches the page finds nothing — and because the response body is the same `Requested function was not found` string that generic `NOT_FOUND` returns, the existing `NOT_FOUND` entry reads like it covers the case when it doesn't. ## What is the new behavior? Both codes are documented under `## Server Errors` with a cause and a remedy, in the page's existing `**Cause:**` / `**Solution:**` shape. - `NOT_FOUND_FUNCTION_BLOB` goes directly after `### NOT_FOUND`, since readers hitting it will scan for `NOT_FOUND` first. The cause explains the metadata/bundle version mismatch (concurrent or batched deploys double-incrementing the metadata version), notes that the message is identical to `NOT_FOUND` so the `sb-error-code` header is the distinguisher, and links the existing [Edge Function 404 error response](https://supabase.com/docs/guides/troubleshooting/edge-function-404-error-response) troubleshooting guide. Solution: redeploy with the latest CLI, avoid concurrent deploys of the same function, contact support to re-sync metadata if it persists. - `LOAD_FUNCTION_UNBUNDLING_ERROR` goes at the end, keeping the `LOAD_FUNCTION_*` cluster together. Cause: the bundle was fetched but decompression/parsing failed, which points at a corrupt or partially-written bundle. Solution: redeploy, contact support if it persists. ## Additional context Both codes are real and currently emitted by `supabase/edge-functions-ingress` (`main`): - `NOT_FOUND_FUNCTION_BLOB` — 404, declared at `src/main/errors.ts:29`, emitted at `src/main/cache.ts:180` - `LOAD_FUNCTION_UNBUNDLING_ERROR` — 503, declared at `src/main/errors.ts:27`, emitted at `src/main/cache.ts:226` Both were introduced by supabase/edge-functions-ingress#464. ### Notes for reviewer - **Scope.** The comment on #47739 asked only for `NOT_FOUND_FUNCTION_BLOB`. `LOAD_FUNCTION_UNBUNDLING_ERROR` is included because it shipped in the same ingress PR and is equally undocumented — happy to drop it if you'd rather keep this PR to exactly what was requested. - **No HTTP statuses in the copy.** The 404/503 above are deliberately left out of the page text, because the Error codes page states no HTTP status anywhere for any code. Adding them here would be a format departure. Easy to add if you'd prefer to start including them. - **Message mismatch, not fixed here.** `apps/docs/content/troubleshooting/edge-function-404-error-response.mdx` declares `message = "Function deployment bundle not found"` for `NOT_FOUND_FUNCTION_BLOB`, but the runtime actually emits `"Requested function was not found"` (`cache.ts:181`), which matches the response pasted in #47739. Left untouched in this PR — flagging it for a follow-up. ### Checks run - `prettier --check` on the changed file: passes. - `supa-mdx-lint` (v0.3.2) on the changed file: no new findings. The one remaining warning (`error-codes.mdx:11` — "Use 'view and resolve errors' instead of 'handle errors'") is pre-existing on `master` and untouched here. - The `{/* supa-mdx-lint-disable Rule001HeadingCase */}` pragma at line 8 sits above both new H3s, so the uppercase headings pass. --- _Generated by [Claude Code](https://claude.ai/code/session_01Qw5D2wdScBN5TWuA2FgnDW)_ --------- Co-authored-by: Claude --- .../content/guides/functions/error-codes.mdx | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/apps/docs/content/guides/functions/error-codes.mdx b/apps/docs/content/guides/functions/error-codes.mdx index cd9e1a4bb5d..e6117c0592f 100644 --- a/apps/docs/content/guides/functions/error-codes.mdx +++ b/apps/docs/content/guides/functions/error-codes.mdx @@ -264,6 +264,21 @@ These errors indicate issues with function loading, execution, or the underlying **Solution:** Try redeploying your function and wait a few minutes to make sure all regions have been updated. +### NOT_FOUND_FUNCTION_BLOB + +**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](/docs/guides/troubleshooting/edge-function-404-error-response). + +**Common causes:** + +- Two deploys of the same function running concurrently, double-incrementing the metadata version +- 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, such as overlapping GitHub Actions runs +- If the problem persists, contact support so your function metadata can be re-synced + ### BOOT_ERROR **Cause:** Your Edge Function failed to start. @@ -302,3 +317,12 @@ These errors indicate issues with function loading, execution, or the underlying - Try redeploying your function - If the problem persists, contact support + +### LOAD_FUNCTION_UNBUNDLING_ERROR + +**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:** + +- Try redeploying your function +- If the problem persists, contact support