The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
TypeScript aialternativeauthdatabasedenoembeddingsexamplefirebasenextjsoauth2pgvectorpostgispostgrespostgresqlpostgrestrealtimesupabasevectorswebsockets
docs: Supabase edge functions 404 troubleshooting (#43488)
TheOtherBrian17157fa3710c4
diff --git a/apps/docs/content/troubleshooting/edge-function-401-error-response.mdx b/apps/docs/content/troubleshooting/edge-function-401-error-response.mdxnew file mode 100644index 00000000000..b0aadb87cda--- /dev/null+++ b/apps/docs/content/troubleshooting/edge-function-401-error-response.mdx@@ -0,0 +1,160 @@+---+title = "Edge Function 401 error response"+topics = [ "functions" ]+keywords = [ "401", "error" ]++[[errors]]+http_status_code = 401+message = "Invalid JWT"+---++The function rejected the request for lacking the appropriate authorization headers.++## Context for the error++#### The JWT verification check++By default, edge functions are configured to check requests for a valid [legacy key](/docs/guides/api/api-keys#overview).++#### How the check causes 401 errors++The check will fail and return a 401 permission error if:++- The request includes an invalid legacy key, or+- The request uses the newer asymmetric keys instead of a legacy key.++#### What this check actually does++This validation provides limited security value. It only confirms that the request includes a legacy token associated with your project, such as the anon key.++It does not validate the user's identity or permissions beyond that.++Because the security check is weak, it was deprecated when used with the new asymmetric keys.++## Solving the error++### Step 1: Identifying the error++<Admonition type="note">++If the tests return a 401 but don't match the criteria below, the error is coming from your app logic, not the JWT check.++</Admonition>++### Inspecting the return message++When an edge function fails due to a platform 401 error, it will return the error:++```json+{+ "code": 401,+ "message": "Invalid JWT"+}+```++### Inspecting the logs++Your code may return a 401 error due to its own logic++```js+return new Response(JSON.stringify(data), {+ headers: { ...corsHeaders, 'Content-Type': 'application/json' },+ status: 401, // app logic returning a 401+})+```++A 401 status code alone doesn't confirm a JWT check failure by itself. The log must also lack an `execution_id`.++++Instead of manually reviewing the logs, you can run the below query in the [log explorer](</dashboard/project/_/logs/explorer?q=SELECT+DISTINCT%0A++++req.pathname+AS+function_name,%0A++++res.status_code%0A++FROM+function_edge_logs%0A++CROSS+JOIN+UNNEST(metadata)+AS+metadata+%0A++CROSS+JOIN+UNNEST(metadata.request)+AS+req+%0A++CROSS+JOIN+UNNEST(metadata.response)+AS+res+%0AWHERE+status_code+=+401+AND+metadata.execution_id+IS+NULL%0ALIMIT+10;&its=&ite=>) to get a list of functions that were impacted by the check:++```sql+select distinct+ req.pathname as function_name,+ res.status_code+from+ function_edge_logs+ cross join UNNEST(metadata) as metadata+ cross join UNNEST(metadata.request) as req+ cross join UNNEST(metadata.response) as res+where status_code = 401 and metadata.execution_id is null+limit 10;+```++### Step 2: Disabling the JWT check++The JWT check provides minimal security benefits, so we now recommend handling authentication through app logic instead. See the [Edge Function Auth Doc](/docs/guides/functions/auth) for details.++If you've migrated to [asymmetric keys (publishable/secret)](/dashboard/project/_/settings/api-keys) or no longer need the JWT check, you can disable it using one of the three options below:++<Accordion+ type="default"+ openBehaviour="multiple"+ chevronAlign="right"+ justified+ size="medium"+ className="text-foreground-light mt-8 mb-6"+>+ <div className="border-b mt-3 pb-3">+ <AccordionItem+ header="In the Dashboard"+ id="item-1"+ >+ In the [Function Dashboard](/dashboard/project/_/functions/), under the offending function's detail tab, you can toggle off the check:++ +++ </AccordionItem>++ </div>+ <div className="border-b mt-3 pb-3">+ <AccordionItem+ header="With the Management API"+ id="item-2"+ >++ 1. Generate a secret token in the [Account Preferences Dashboard](/dashboard/account/tokens)+ 2. Get your project ID from the [General Settings](/dashboard/project/_/settings/general)+ 3. Substitute in the `PROJECT_ID`, `FUNCTION_NAME`, and `SECRET_TOKEN` in below [management endpoint](/docs/reference/api/v1-update-a-function). Then execute the request from a terminal environment++ ```sh+ # remember to substitute in your PROJECT_ID, FUNCTION_NAME, and SECRET_TOKEN++curl 'https://api.supabase.com/v1/projects/PROJECT_ID/functions/FUNCTION_NAME?verify_jwt=false' \+--request PATCH \+--header 'Content-Type: application/vnd.denoland.eszip' \+--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \+--data '""'++````+</AccordionItem>++ </div>++ <div className="border-b mt-3 pb-3">+ <AccordionItem+ header="With the Supabase CLI"+ id="item-3"+ >++With the [Supabase CLI](/docs/guides/local-development/cli/getting-started), you can redeploy your edge function without the JWT check:++```sh+supabase functions deploy hello-world --no-verify-jwt+````++ </AccordionItem>++ </div>+</Accordion>++If you would like to continue using the JWT check, make sure that your [Supabase Client](/docs/guides/api/rest/client-libs) only uses your [legacy keys](/dashboard/project/_/settings/api-keys/legacy).++## Additional resources++- [Securing Edge Functions](/docs/guides/functions/auth)+- [Debugging Edge Functions](/docs/guides/functions/logging)+- [Quickstart Deployment: Dashboard](/docs/guides/functions/quickstart-dashboard)+- [Quickstart Deployment: CLI](/docs/guides/functions/quickstart)diff --git a/apps/docs/content/troubleshooting/edge-function-404-error-response.mdx b/apps/docs/content/troubleshooting/edge-function-404-error-response.mdxnew file mode 100644index 00000000000..85a709b00c8--- /dev/null+++ b/apps/docs/content/troubleshooting/edge-function-404-error-response.mdx@@ -0,0 +1,117 @@+---+title = "Edge Function 404 error response"+topics = [ "functions" ]+keywords = [ "404", "error" ]++[[errors]]+http_status_code = 404+code = "NOT_FOUND"+message = "Requested function was not found"+---++The edge function is not recognized by Supabase++## Context for the error++If the Supabase Edge Function Runtime does not recognize the function specified in the URL endpoint:++```sh+https://PROJECT_REF.supabase.co/functions/v1/UNRECOGNIZED_FUNCTION_NAME+```++then the runtime will return a 404 error.++## Solving the error++### Step 1: Identifying the error++<Admonition type="note">++If the tests return a 404 but don't match the criteria below, the error is coming from your app logic, not the JWT check.++</Admonition>++### Inspecting the return message from the request++<Admonition type="caution">++Platform 404 errors cannot be detected in the browser. Instead, to confirm 404s from the browser, you must [check the logs](#inspecting-the-logs) instead.++Browsers misreport 404s as generic `CORS errors`. As a result, the [Supabase JavaScript client](/docs/reference/javascript/introduction) surfaces only a generic message: `Failed to send a request to the Edge Function`.++</Admonition>++When an edge function fails due to a platform 404 error, it will return the error:++```json+{+ "code": "NOT_FOUND",+ "message": "Requested function was not found"+}+```++### Inspecting the logs++<Admonition type='tip'>++Always configure an appropriate time frame when using the log explorer++ ++</Admonition>++One cannot inspect the function dashboard to find platform 404 errors, instead, you must run the below query in the [log explorer](/dashboard/project/_/logs/explorer?q=SELECT+DISTINCT%0A++++req.pathname+AS+function_name%2C%0A++++res.status_code%0AFROM+function_edge_logs%0ACROSS+JOIN+UNNEST%28metadata%29+AS+metadata+%0ACROSS+JOIN+UNNEST%28metadata.request%29+AS+req+%0ACROSS+JOIN+UNNEST%28metadata.response%29+AS+res+%0AWHERE+%0A++++status_code+%3D+404+%0A++++++++AND+%0A++++metadata.execution_id+IS+NULL%0ALIMIT+10%3B). Results will show all requests that reached Supabase but were rejected as unrecognizable.++```sql+select distinct+ req.pathname as function_name,+ res.status_code+from+ function_edge_logs+ cross join UNNEST(metadata) as metadata+ cross join UNNEST(metadata.request) as req+ cross join UNNEST(metadata.response) as res+where status_code = 404 and metadata.execution_id is null+limit 10;+```++### Step 2: Check the function for typos++In your code, make sure your function name doesn't have any typos, such as:++- miscapitalization+- em-dashes instead of dashes+- misplaced characters+- unnecessary slashes `///`++### Step 3: Try calling the function from the dashboard++When selecting your function in the [Function Dashboard](/dashboard/project/_/functions), you should have the option to make a test call:++++If the call works, consider double checking your code for typos or to see if it is overwriting the function name dynamically. Otherwise, go on to step 4.++### Step 4: Redeploy the function++If step 3 fails, it may be a sign of an internal bug and it may be necessary to redeploy your function. This can be done within the [Function Dashboard](/dashboard/project/_/functions) under the respective function's code tab:++++Alternatively, if you develop locally, you can redeploy the function with the [Supabase CLI](/docs/guides/local-development/cli/getting-started?queryGroups=platform&platform=macos):++```sh+supabase functions deploy FUNCTION_NAME++# If you want to deploy all functions, run the `deploy` command without specifying a function name:+supabase functions deploy+```++Then write in a ticket to [Supabase Support](/dashboard/support/new)++## Additional resources++- [Securing Edge Functions](/docs/guides/functions/auth)+- [Debugging Edge Functions](/docs/guides/functions/logging)+- [Quickstart Deployment: Dashboard](/docs/guides/functions/quickstart-dashboard)+- [Quickstart Deployment: CLI](/docs/guides/functions/quickstart)diff --git a/apps/docs/public/img/troubleshooting/401_edge_functions_toggle_off_JWT_check.png b/apps/docs/public/img/troubleshooting/401_edge_functions_toggle_off_JWT_check.pngnew file mode 100644index 00000000000..34be98771e2Binary files /dev/null and b/apps/docs/public/img/troubleshooting/401_edge_functions_toggle_off_JWT_check.png differdiff --git a/apps/docs/public/img/troubleshooting/401_in_the_logs.png b/apps/docs/public/img/troubleshooting/401_in_the_logs.pngnew file mode 100644index 00000000000..77aaac43325Binary files /dev/null and b/apps/docs/public/img/troubleshooting/401_in_the_logs.png differdiff --git a/apps/docs/public/img/troubleshooting/edge_function_404_redeploy.png b/apps/docs/public/img/troubleshooting/edge_function_404_redeploy.pngnew file mode 100644index 00000000000..04f971711b4Binary files /dev/null and b/apps/docs/public/img/troubleshooting/edge_function_404_redeploy.png differdiff --git a/apps/docs/public/img/troubleshooting/edge_function_404_set_timeframe.png b/apps/docs/public/img/troubleshooting/edge_function_404_set_timeframe.pngnew file mode 100644index 00000000000..57465225be1Binary files /dev/null and b/apps/docs/public/img/troubleshooting/edge_function_404_set_timeframe.png differdiff --git a/apps/docs/public/img/troubleshooting/edge_function_404_test_call.png b/apps/docs/public/img/troubleshooting/edge_function_404_test_call.pngnew file mode 100644index 00000000000..85fd737effcBinary files /dev/null and b/apps/docs/public/img/troubleshooting/edge_function_404_test_call.png differdiff --git a/apps/docs/public/img/troubleshooting/edge_functions_401_verify_jwt.png b/apps/docs/public/img/troubleshooting/edge_functions_401_verify_jwt.pngnew file mode 100644index 00000000000..dc8ca2b3037Binary files /dev/null and b/apps/docs/public/img/troubleshooting/edge_functions_401_verify_jwt.png differdiff --git a/supa-mdx-lint/Rule003Spelling.toml b/supa-mdx-lint/Rule003Spelling.tomlindex 110de046c84..c59ca38b309 100644--- a/supa-mdx-lint/Rule003Spelling.toml+++ b/supa-mdx-lint/Rule003Spelling.toml@@ -59,6 +59,8 @@ allow_list = ["[Dd]ropdown","DuckDB","EarlyDrop",+ "[Ee]m-dash",+ "[Ee]m-dashes","[Ee]nqueues?","[Ee]ntrypoints?","[Ee]nums?",@@ -91,6 +93,8 @@ allow_list = ["[Mm]icroservices?","microtasks","[Mm]iddlewares?",+ "[Mm]iscapitalization",+ "[Mm]isreport","[Mm]onorepos?","[Mm]ultimodal","[Mm]ultipart",