错误代码

当 Edge Function 请求失败时，响应会包含一个 sb-error-code 头，用于标识具体的错误。你可以在 HTTP 客户端或应用代码中检查这个头，以便以编程方式检测和处理错误。

🌐 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.

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

糟糕的实现错误 #

🌐 Bad Implementation Errors

这些错误是因为你的函数代码或逻辑有问题，需要更新实现。

🌐 These errors are caused by issues in your function's code or logic which requires updating its implementation.

EDGE_FUNCTION_ERROR#

原因： 你的 Edge 函数抛出了未处理的错误或返回了 5XX 状态码。

1
// ...
2
3
function process() {
4
  throw new Error('Some unhandled error')
5
}
6
7
export default {
8
  fetch: withSupabase({ auth: 'none' }, async () => {
9
    process()
10
11
    return new Response()
12
  }),
13
}

解决方案：

• 确保你用 try-catch 块捕捉代码逻辑中的错误。

1
function process() {
2
  throw new Error('Some unhandled error')
3
}
4
5
// ...
6
7
try {
8
  process()
9
  return new Response()
10
} catch (e) {
11
  console.error('Process fail:', e)
12
  return new Response(null, { status: 500 })
13
}

IDLE_TIMEOUT#

原因： 你的 Edge 函数在 请求超时限制 内没有响应。

常见原因：

• 长时间运行的数据库查询
• 外部 API 调用慢
• 无限循环或阻塞操作

解决方案：

• 优化慢操作
• 给外部请求加上超时处理
• 考虑把大操作拆成小块

工作者资源限制，工作者数量限制 #

🌐 WORKER_RESOURCE_LIMIT, WORKER_LIMIT

原因： 你的 Edge Function 执行因超出资源限制而被停止。Edge Function 日志应该会显示是哪一项 资源限制 被超出了。

常见原因：

• 内存使用超出可用限制
• CPU 时间超出执行配额
• 同时操作太多了

解决方法： 查看你的 Edge Function 日志，看看哪个资源限制被超出了，然后相应地优化你的函数。

WORKER_ERROR#

原因： 你的 Edge 函数抛出了一个未捕获的异常。

1
// ...
2
3
function initSomething() {
4
  throw new Error('Some unhandled error')
5
}
6
7
initSomething() // Error threw outside request handler
8
9
export default {
10
  fetch: withSupabase({ auth: 'none' }, async () => {
11
    return new Response()
12
  }),
13
}

常见原因：

• 你的函数代码中出现未处理的 JavaScript 错误，发生在请求处理器之外
• 异步操作缺少错误处理
• 无效的 JSON 解析

解决方法： 查看你的 Edge Function 日志以确定具体错误，并在代码中添加适当的错误处理。

INVALID_RESPONSE_STATUS_CODE#

原因: 你的边缘函数返回了一个无效的 HTTP 状态码 — 不等于 101 并且超出 [200, 599] 范围

常见原因：

• 代理一个返回无效HTTP状态码的外部服务

1
// ...
2
3
export default {
4
  fetch: withSupabase({ auth: 'none' }, async (req) => {
5
    // Fails in case this proxied server return a status >599
6
    return fetch('https://some-server-to-proxy', {
7
      method: req.method,
8
      headers: req.headers,
9
      body: req.body,
10
    })
11
  }),
12
}

解决方案：

• 确保你返回的是有效的 HTTP 状态码
• 对于代理端点，不要直接返回 fetch() 结果；而是返回一个新的 Response，并用 try-catch 块封装起来

1
// ...
2
3
export default {
4
  fetch: withSupabase({ auth: 'none' }, async (req) => {
5
    try {
6
      const res = await fetch('https://some-server-to-proxy', {
7
        method: req.method,
8
        headers: req.headers,
9
        body: req.body,
10
      })
11
12
      // Creating a 'new Response()' ensures contructor checks
13
      return new Response(await res.body, {
14
        headers: res.headers,
15
        status: res.status,
16
        statusText: res.statusText,
17
      })
18
    } catch (e) {
19
      console.error('Proxy Error', e)
20
      return new Response(null, { status: 502 })
21
    }
22
  }),
23
}

身份验证错误 #

🌐 Authentication Errors

这些错误会在请求中缺少、格式错误或不支持的 JWT 令牌时发生。要解决这些问题，需要确保你的请求包含有效的授权头，或者对公共端点禁用 JWT 验证。 更多信息，请参见 授权头 和 保护边缘函数。

🌐 These errors occur when the request contains a missing, malformed, or unsupported JWT token. Fixing them requires ensuring your requests include a valid authorization header, or disabling JWT verification for public endpoints. For further information, see Authorization headers and Securing Edge Functions.

UNAUTHORIZED_NO_AUTH_HEADER#

原因： Edge 函数启用了 JWT 验证，但请求缺少 Authorization 或 apikey 头。

解决方案：

• 确保你在 Authorization 头中传递了有效的 JWT 令牌
• 确认你是否在 apikey 头中发送了 API 密钥
• 对于网页钩子或公共端点，考虑关闭 JWT 验证

UNAUTHORIZED_ASYMMETRIC_JWT#

原因： Edge 功能启用了 JWT 验证，但 Authorization 头包含无效的非对称 ES256 | RS256 令牌。

解决方案：

• 确保你在 Authorization 头中传递了有效的用户 JWT 令牌
• 检查一下你的令牌是否已过期

UNAUTHORIZED_LEGACY_JWT#

原因: Edge 函数启用了 JWT 验证，但 Authorization 头包含无效的传统 HS256 令牌。

解决方案：

• 确保你在 Authorization 头中传递的是有效的旧版 JWT 令牌
• 检查一下你的令牌是否已过期
• 确认旧的 JWT 密钥没有被撤销或禁用

UNAUTHORIZED_UNSUPPORTED_TOKEN_ALGORITHM#

原因： Edge 函数启用了 JWT 验证，但 Authorization 头部不包含 ES256 | RS256 | HS256 令牌。

解决方案：

• 确保你在 Authorization 头中传递的是有效的 Supabase 颁发的 JWT 令牌

UNAUTHORIZED_INVALID_JWT_FORMAT#

原因： Edge 函数启用了 JWT 验证，但 Authorization 头不符合 Bearer <JWT Token> 格式。

解决方案：

• 检查一下你是否在 Authorization 头里传了 Bearer <JWT Token>
• 确保你在 apikey 头部发送 API 密钥，而不是 Authorization
• 对于网页钩子或公共端点，考虑关闭 JWT 验证

请求错误 #

🌐 Request Errors

这些错误表明请求本身有问题，通常需要改变函数的调用方式。

🌐 These errors indicate issues with the request itself, which typically require changing how the function is called.

RATE_LIMIT_EXCEEDED#

原因： 平台检测到递归或嵌套函数调用行为。

常见原因：

• 多个函数间调用
• 递归或循环调用

解决方案：

• 在再次调用你的函数之前，使用错误信息中建议的重试时间（以秒为单位）
• 确保你没有进行不必要的单独调用；尽量使用批量操作
• 将大量工作委托给队列，而不是递归调用其他 Edge Functions

INVALID_URL#

原因： 平台拒绝了一个格式不正确的 URL。

解决方案：

• 确保你使用的是有效的格式化 URL

服务器错误 #

🌐 Server Errors

这些错误表明函数加载、执行或底层平台存在问题。

🌐 These errors indicate issues with function loading, execution, or the underlying platform.

NOT_FOUND#

原因： 在特定区域未找到 Edge Function 元数据或文件，或者它们丢失了。

解决方案： 尝试重新部署你的函数，并等待几分钟以确保所有区域都已更新。

NOT_FOUND_FUNCTION_BLOB#

原因: 你的 Edge Function 元数据已解析，但其部署包在存储中缺失，无法加载（元数据指向的版本与存储的包不同）。这会返回和 NOT_FOUND 相同的 Requested function was not found 消息，所以是 sb-error-code 头部将它们区分开 — 详情见 Edge Function 404 错误响应。

常见原因：

• 两个相同函数的部署同时运行，对元数据版本进行双重递增
• 使用 /deploy?bundleOnly=true 批量部署时，大量元数据更新失败了

解决方案：

• 用最新版本的 Supabase CLI 重新部署你的函数
• 避免同时部署同一个函数，比如重叠的 GitHub Actions 运行
• 如果问题仍然存在，请联系支持，以便重新同步你的功能元数据

BOOT_ERROR#

**原因：**你的 Edge 函数启动失败。

常见原因：

• 语法错误导致函数无法加载
• 导入错误或缺少依赖
• 无效的函数配置

解决方案： 查看你的 Edge Function 日志，同时确认你的函数代码可以在本地通过 supabase functions serve 执行。

LOAD_FUNCTION_ERROR#

原因: 平台无法加载你的函数元数据或文件。

解决方案：

• 稍等一下再试着调用你的函数
• 如果问题仍然存在，联系支持

LOAD_FUNCTION_METADATA_ERROR#

原因： 平台无法获取你的函数元数据，可能是由于外部缓存问题。

解决方案：

• 在再次调用你的函数前等几分钟
• 如果问题仍然存在，联系支持

LOAD_FUNCTION_INVALID_ENTRYPOINT_PATH_ERROR#

原因： 你的 Edge Function 元数据损坏或包含无效的入口点。

解决方案：

• 试着重新部署你的函数
• 如果问题仍然存在，联系支持

LOAD_FUNCTION_UNBUNDLING_ERROR#

原因: 你的 Edge Function 部署包已被获取，但无法解包，因为解压或解析失败。这通常意味着该部署包已损坏或仅部分写入。

解决方案：

• 试着重新部署你的函数
• 如果问题仍然存在，联系支持