Edge Function 401 error response

A 401 response from an Edge Function means either:

• The function failed the legacy auth verification check
• Your function's logic deliberately returned a 401 response

Quick triage#

Check the response body returned by the request

Case 1: "Invalid Token" or "Missing authorization header"#

1
{ "code": 401, "message": "Invalid Token or Protected Header formatting" }

1
{ "code": 401, "message": "Missing authorization header" }

Both of these messages come from the legacy auth verification check

Go to: Built-in JWT check failures

Case 2: Custom message or empty body#

If the response body contains a message you coded, or nothing at all, then your function code did execute and returned a 401 itself.

Go to: Your function returned a 401

Case 3: Not sure#

Run this query in the SQL Editor to classify recent 401s:

1
select
2
  timestamp,
3
  log_attributes['request.pathname'] as function_name,
4
  case
5
    when log_attributes['execution_id'] != '' then 'your_code_returned_401'
6
    when log_attributes['execution_id'] = ''
7
    and (
8
      log_attributes['request.sb.apikey.apikey.prefix'] != ''
9
      or (
10
        log_attributes['request.sb.jwt.authorization.payload.algorithm'] != ''
11
        and log_attributes['request.sb.jwt.authorization.payload.algorithm'] != 'HS256'
12
      )
13
    ) then 'incompatible_keys'
14
    when log_attributes['execution_id'] = ''
15
    and (
16
      log_attributes['request.sb.jwt.authorization.invalid'] != ''
17
      or log_attributes['request.sb.apikey.apikey.error'] != ''
18
      or log_attributes['request.sb.jwt.authorization.payload.algorithm'] = 'HS256'
19
    ) then 'invalid_key'
20
    when log_attributes['execution_id'] = ''
21
    and log_attributes['request.sb.jwt.authorization.payload.algorithm'] = ''
22
    and log_attributes['request.sb.apikey.apikey.prefix'] = '' then 'missing_auth_header'
23
  end as cause
24
from logs
25
where
26
  source = 'function_edge_logs'
27
  and toInt32OrZero(log_attributes['response.status_code']) = 401
28
order by timestamp desc
29
limit 50;

Depending on the output, you can use this table to find the appropriate debugging section:

Your function returned a 401#

Your function ran, and somewhere in your code, its logic returned a 401.

Example:

1
return new Response(JSON.stringify(data), {
2
  headers: { ...corsHeaders, 'Content-Type': 'application/json' },
3
  status: 401, // <-- you set this
4
})

How to fix:

1. Search your function code for 401. Look for explicit status codes on Response objects.
2. Trace the condition that triggered it. If you're interacting with a third-party API in your code, that service may be returning 401 that you're forwarding in the response object.
3. Add logging before the return so future occurrences leave a trace:

1
console.error('Returning 401 - reason:', reason)

See: Error handling in Edge Functions

Built-in JWT check failures#

Supabase Edge Functions have a legacy auth verification check that runs before your code. When it fails, your function never executes, and you get a 401 with "Invalid JWT" or "Missing authorization header" directly from the platform.

The subsections below cover specific failure modes.

Incompatible key format#

Your project uses the new asymmetric keys for authentication. However, the legacy auth verification check only understands the legacy format.

Fix: Disable the built-in JWT check using one of the below methods and optionally handle auth in your function code

Invalid key#

The built-in check is enabled and the key you sent doesn't match your project's keys.

Fix (recommended): Disable the built-in check using the steps in Incompatible key format.

Fix (alternative): If you want to keep the built-in check, ensure you're sending a valid key. Use one of your legacy API keys with the Supabase client library when making your request.

1
const supabase = createClient('https://xyzcompany.supabase.co', 'anon-key-or-service_role-key')

Missing authorization header#

The built-in check is enabled but your request has no Authorization header at all.

If you're using a Supabase client library, the header is added automatically. If you're calling the function from an external client (cURL, fetch, etc.), you need to supply it:

1
curl -L -X POST 'https://PROJECT_REF.supabase.co/functions/v1/hello-world' \
2
  -H 'Authorization: Bearer YOUR_ANON_OR_SERVICE_ROLE_KEY' \
3
  --data '{"name":"Functions"}'

Alternatively, you can disable the built-in check entirely (see Incompatible key format).

Additional resources#

• Securing Edge Functions with Auth
• Logging Edge Function Requests
• Error Handling Edge Functions
• Quickstart: Dashboard deployment
• Quickstart: CLI deployment

Still stuck?#

• Check the Discord, Supabase GitHub Discussions, and Reddit page for similar reports that can help with debugging
• Open a support ticket for your project if the problem persists and you believe it is a platform issue