Skip to content

Edge Function 401 error response

Last edited: 8/12/2026

Edge Function 返回 401 响应意味着以下情况之一：

🌐 A 401 response from an Edge Function means either:

快速分诊 #

🌐 Quick triage

检查请求返回的响应体

🌐 Check the response body returned by the request

情况 1："Invalid Token" 或 "Missing authorization header"#

🌐 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

前往：内置 JWT 检查失败

🌐 Go to: Built-in JWT check failures

案例 2：自定义消息或空内容 #

🌐 Case 2: Custom message or empty body

如果响应体包含你编写的消息，或者根本没有内容，那么你的函数代码确实执行过，并且自己返回了 401。

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

前往：你的函数返回了 401

🌐 Go to: Your function returned a 401

情况3：不确定 #

🌐 Case 3: Not sure

在 Log Explorer 中运行此查询以分类最近的 401 错误：

🌐 Run this query in Log Explorer to classify recent 401s:

1
select
2
  cast(timestamp as datetime) as timestamp,
3
  req.pathname as function_name,
4
  case
5
    when metadata.execution_id is not null then 'your_code_returned_401'
6
    when metadata.execution_id is null
7
    and (
8
      new_auth.prefix is not null
9
      or legacy_payload.algorithm != 'HS256'
10
    ) then 'incompatible_keys'
11
    when metadata.execution_id is null
12
    and (
13
      (legacy_auth_data.invalid is not null or new_auth.error is not null)
14
      or legacy_payload.algorithm = 'HS256'
15
    ) then 'invalid_key'
16
    when metadata.execution_id is null
17
    and legacy_auth_data is null
18
    and new_auth.prefix is null then 'missing_auth_header'
19
  end as cause
20
from
21
  function_edge_logs
22
  -- unnesting metadata
23
  cross join UNNEST(metadata) as metadata
24
  cross join UNNEST(metadata.request) as req
25
  cross join UNNEST(metadata.response) as res
26
  -- unnesting auth details
27
  left join UNNEST(req.sb) as sb
28
  left join UNNEST(sb.apikey) as apikey
29
  left join UNNEST(apikey.authorization) as new_auth
30
  left join UNNEST(sb.jwt) as legacy_jwt
31
  left join UNNEST(legacy_jwt.authorization) as legacy_auth_data
32
  left join UNNEST(legacy_auth_data.payload) as legacy_payload
33
where res.status_code = 401
34
order by timestamp desc
35
limit 50;

根据输出情况，你可以使用此表找到相应的调试部分：

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

值前往
your_code_returned_401你的函数返回了 401
incompatible_keys不兼容的密钥格式
invalid_key无效的密钥
missing_auth_header缺少授权头

你的函数返回了 401 #

🌐 Your function returned a 401

你的函数运行了，但在你的代码某处，它的逻辑返回了一个 401。

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

示例：

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

如何修复：

  1. 在你的函数代码中搜索 401。查看 Response 对象上的明确状态码。
  2. 追踪触发它的条件。如果你的代码中在与第三方 API 交互，该服务可能返回 401 状态码，而你在响应对象中转发了它。
  3. 在返回之前添加日志，这样将来发生时可以留下记录：
1
console.error('Returning 401 - reason:', reason)

参见：Edge Functions 中的错误处理

🌐 See: Error handling in Edge Functions

内置 JWT 检查失败 #

🌐 Built-in JWT check failures

Supabase Edge Functions 有一个老的认证验证检查，会在你的代码运行前执行。如果它失败了，你的函数根本不会执行，而且你会直接从平台收到带有 "Invalid JWT" 或 "Missing authorization header" 的 401 错误。

🌐 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

你的项目使用了new asymmetric keys进行认证。不过，legacy auth verification check只认旧的格式。

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

修复： 使用下面的方法之一禁用内置的 JWT 检查，并可选择在你的函数代码中处理认证

无效的密钥 #

🌐 Invalid key

内置检查已启用，你发送的密钥和你项目的密钥不匹配。

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

修复（推荐）： 按照 不兼容密钥格式 中的步骤禁用内置检查。

修复（可选方案）： 如果你想保留内置检查，请确保你发送的是有效的密钥。在发出请求时，使用你的传统 API 密钥和Supabase 客户端库。

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

缺少授权头 #

🌐 Missing authorization header

内置检查已启用，但你的请求根本没有 Authorization 头。

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

如果你使用的是 Supabase 客户端库，头信息会自动添加。如果你是从外部客户端（cURL、fetch 等）调用该函数，你需要自己提供它：

🌐 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

还卡住吗？ #

🌐 Still stuck?