---
title: "Troubleshooting"
description: "Determine the failing Nexus layer, provider-call boundary, request identifier, and safe retry action."
---

> Documentation Index
> Fetch the complete documentation index at: https://nexus.microvoid.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

## Outcome

从 Gateway 的稳定错误 Envelope 判断故障层、Provider 是否被调用、能否重试，以及后端应查询哪个 Request ID。

## Start with the response

```json
{
  "error": {
    "message": "Quota is insufficient for this request",
    "type": "rate_limit_error",
    "param": null,
    "code": "quota_exceeded",
    "request_id": "req_01J...",
    "reset_at": "2026-08-21T00:00:00.000Z"
  }
}
```

优先保存响应 Header `x-nexus-request-id`；错误 JSON 的 `error.request_id` 应与它一致。`x-nexus-quota-remaining` 和 `x-nexus-quota-reset` 只在相关响应存在。不要用 Trace ID、Provider Request ID 或 Admin API Request ID 替代 Gateway Request ID。

## Gateway error matrix

| HTTP / code                         | Layer                     | Provider called? | Retry?              | First check                            |
| ----------------------------------- | ------------------------- | ---------------- | ------------------- | -------------------------------------- |
| 400 `invalid_gateway_route`         | Request routing           | No               | No, fix request     | 必须匹配 `/providers/{UUID}/{path...}` |
| 400 `unsafe_provider_path`          | SSRF guard                | No               | No, fix request     | 后缀是否包含绝对 URL/不安全引用        |
| 400 `invalid_usage_request`         | Usage Inspector input     | No               | No, fix payload     | 可计量端点要求的请求结构               |
| 401 `invalid_inference_key`         | Authentication            | No               | No, rotate/fix      | Key 类型、撤销和过期                   |
| 403 `workspace_access_denied`       | Access                    | No               | No, fix lifecycle   | Access 状态/起止时间、当前 Period      |
| 404 `provider_connection_not_found` | Workspace isolation       | No               | No, fix ID/status   | UUID 是否属于同一 Workspace 且 ACTIVE  |
| 409 `metering_unsupported`          | Usage Inspector           | No               | No, change endpoint | 端点无 Inspector，未开启不计量透传     |
| 429 `quota_exceeded`                | Quota admission           | No               | At reset/change     | `availableUnits` 与 `reset_at`         |
| 502 `provider_configuration_error`  | Saved connection          | No               | No, repair config   | Base URL、密文和 Keyring 配置          |
| 502 `provider_unavailable`          | Provider transport        | Attempted        | Bounded backoff     | Provider Attempt 和上游状态            |
| 503 `access_unavailable`            | PostgreSQL/Access service | No               | Backoff             | DB/Access Readiness、连接池            |
| 504 `provider_first_byte_timeout`   | Provider transport        | Yes              | Risk-aware          | Provider Attempt，是否可能已执行       |
| 504 `provider_overall_timeout`      | Provider stream           | Yes              | Risk-aware          | 已输出内容、Reservation 终态           |

上游 Provider 自己返回的状态和 Body 可以被代理；此时 Provider 已调用。保留 Nexus Request ID 和 Provider Attempt ID，再按上游错误语义处理。

## Request reached no provider

对 Authentication、Access、Quota、Inspector、Connection Resolution 或 SSRF Guard 的拒绝，不应存在 Provider Attempt。检查：

1. `ApiKeyBinding → WorkspaceAccess → Workspace` 是否解析成功。
2. Access 是否 `ACTIVE` 且未越过 `accessEndsAt`。
3. 当前 QuotaPeriod 的 `availableUnits` 是否覆盖 Reservation。
4. UUID 是否为同一 Workspace 中 ACTIVE 的 ProviderConnection。
5. 路径是否有 Usage Inspector。

## Request reached the provider

查询 Workspace Invocations，再用 Invocation ID 读取详情。对 Timeout、断开和取消，确认 Reservation 最终进入 `SETTLED`、`RELEASED` 或 `EXPIRED`，重复完成事件不能重复扣量。不要因为客户端没收到响应就假定 Provider 没执行。

## Service and deployment failures

| Symptom                                             | Checks                                                        |
| --------------------------------------------------- | ------------------------------------------------------------- |
| Admin Ready, Gateway not Ready                      | `DATABASE_URL`、Auth/Secret Driver、Gateway Port、依赖构建    |
| Gateway Ready, requests return `access_unavailable` | PostgreSQL/Access Service 可用性、连接池、迁移版本            |
| `reservedUnits` 持续增长                            | Worker Readiness、Outbox/Queue Lag、Reservation recovery      |
| Console works but SDK URL fails                     | Console dev proxy 与生产 Gateway Origin 是否混淆              |
| Cloudflare deploy guard fails                       | 全零 KV/Hyperdrive ID、`.invalid` Origin、缺少绑定资源        |
| Provider verify fails                               | 上游权限、Base URL、Redirect、认证和 Timeout；不要输出 Secret |

## Escalation packet

提供以下已脱敏信息：UTC 时间范围、Adapter/版本/Artifact Digest、错误码与状态、Nexus Request ID、Workspace/Access/Connection/Invocation ID、Quota Snapshot 和相关 Health/SLO。不要提供任何 Key、Authorization Header、Provider Secret、数据库 URL 或未批准的请求正文。

## Next steps

- 用 [Quota and metering diagnosis](/cookbook/diagnose-quota-metering) 运行只读事实收集。
- 部署问题从 [Deploy Nexus](/docs/deploy-nexus) 开始。
- 凭证与跨租户问题从 [Security](/docs/security) 开始。

Source: https://nexus.microvoid.io/cookbook/troubleshooting/index.mdx