> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 4 位业务错误码与高频排障手册

本页前半部分汇总部署启动期最常见报错，后半部分提供 `/api/v4/*` 全量 8 个号段（`10xx`–`70xx`）业务错误码排障表。

## 高频部署与启动报错速查

| 报错现象 / 日志关键词                                                         | 根因                                            | 精确修复方法                                                                        |
| :------------------------------------------------------------------- | :-------------------------------------------- | :---------------------------------------------------------------------------- |
| `non-loopback listen requires explicit environment`                  | 监听了 `0.0.0.0:8080` 但未设 `YEARNING_ENVIRONMENT` | 显式设置 `YEARNING_ENVIRONMENT=development` 或 `production`                        |
| `production requires retention.database_dsn`                         | 生产模式未配置独立清理角色 DSN                             | 注入 `YEARNING_RETENTION_DATABASE_DSN`（使用 `yearning_retention` 角色）              |
| `sslmode ... must be verify-ca or verify-full`                       | 生产模式误用了 `sslmode=disable/prefer/require`      | 改为 `YEARNING_DATABASE_SSLMODE=verify-full` 并提供 `SSLROOTCERT`                  |
| `YEARNING_ALLOW_LOOPBACK_TARGETS ... must be disabled in production` | 生产环境开启了本机环回绕过变量                               | 从生产环境变量与 K8s 清单中彻底删除该变量                                                       |
| `keyring file mode ... exceeds maximum`                              | `keyring.json` 文件权限过宽（如 `0644`）               | 执行 `chmod 0400 keyring.json`（K8s 需设 `defaultMode: 0400` + `fsGroup: 10001`）   |
| 网页审批/查询队列不实时刷新或每 60 秒断开                                              | 反代（Nginx/Ingress）开启了响应缓冲或超时过短                 | 为 `/api/v4/events/stream` 添加 `proxy_buffering off; proxy_read_timeout 3600s;` |
| 创建 `change_review` 流程报 `1001`                                        | 尚未创建规则集或未绑定 `rule_set_id`                     | 先在 `/admin/rule-sets` 创建至少 1 套规则集再建流程                                         |
| 编辑数据源保存报 `1001`                                                      | 编辑时不回显 `version_constraint`                   | 每次编辑保存确认重新填入如 `>=8.0,<9.0`                                                    |
| 内置 `admin` 连续输错 5 次报 `1102` 锁定                                       | 触发防爆破锁定，网页端不可解锁                               | 在服务器终端执行 `./yearning --reset-admin-password` 交互重置                             |

***

## `10xx` 通用校验、并发、幂等与配额

| 错误码    | 标识                          | 常见原因与处理方式                                                               |
| :----- | :-------------------------- | :---------------------------------------------------------------------- |
| `1001` | `VALIDATION_FAILED`         | 参数校验失败（数据源缺 `version_constraint`、变更流程缺 `rule_set_id`、通知模板含未知变量或 SQL 片段） |
| `1002` | `RESOURCE_NOT_FOUND`        | 目标资源不存在或当前用户无权查看                                                        |
| `1003` | `VERSION_CONFLICT`          | 乐观锁 `If-Match` 版本过期，刷新页面获取最新版本号后重试                                      |
| `1004` | `CONCURRENT_MODIFICATION`   | 另一请求正在并发修改同一对象，稍后重试                                                     |
| `1005` | `RESOURCE_ALREADY_EXISTS`   | 唯一名称冲突（用户名、数据源名、流程名、规则集名等重复）                                            |
| `1006` | `RESOURCE_REFERENCED`       | 资源仍被下游引用，禁止物理删除，请改为禁用或先解除引用                                             |
| `1007` | `IDEMPOTENCY_KEY_REUSED`    | 同一 `Idempotency-Key` 复用了不同请求体，请生成新的 UUIDv4                              |
| `1008` | `IDEMPOTENCY_IN_PROGRESS`   | 相同幂等键请求仍在执行中，等待完成                                                       |
| `1009` | `CURSOR_EXPIRED`            | 分页游标已失效，回到首页重新拉取                                                        |
| `1010` | `INVALID_STATE_TRANSITION`  | 当前状态机不允许该动作（例如工单已被撤回或已完成）                                               |
| `1011` | `PRECONDITION_REQUIRED`     | 高危设置修改须先调用 `Assess` 接口获取一次性 `impact_token`                              |
| `1012` | `SYSTEM_CAPACITY_EXHAUSTED` | 达到配额上限（例如 AI 助手单用户最多 50 个活跃会话，删旧会话即可释放）                                 |

## `11xx` 身份认证与模板引用保护

| 错误码             | 标识                                          | 处理方式                                                          |
| :-------------- | :------------------------------------------ | :------------------------------------------------------------ |
| `1101`          | `INVALID_CREDENTIALS`                       | 账号密码错误或 LDAP/OIDC 认证失败                                        |
| `1102`          | `ADMIN_PASSWORD_LOCKED`                     | 内置 `admin` 连续输错 5 次锁定，须执行 `./yearning --reset-admin-password` |
| `1103`          | `ADMIN_IMMUTABLE`                           | 内置超级管理员禁止禁用、降权或删除                                             |
| `1104`          | `USER_HAS_ACTIVE_ORDERS`                    | 用户仍有未终结工单或活跃查询授权，禁止删除                                         |
| `1105`          | `USER_REFERENCED_BY_TEMPLATE`               | 用户仍在流程模板中担任审批人或执行人，先从流程移除                                     |
| `1106` / `1107` | `FLOW_REFERENCED` / `DATASOURCE_REFERENCED` | 流程或数据源仍被引用，请改为禁用                                              |
| `1109`          | `PASSWORD_MANAGED_BY_IDENTITY_SOURCE`       | LDAP/OIDC 外部用户不可在 Yearning 内修改密码                              |

## `20xx` AI SQL 预审、预算与提交门禁

| 错误码             | 标识                                              | 处理方式                                                          |
| :-------------- | :---------------------------------------------- | :------------------------------------------------------------ |
| `2001`          | `REVIEW_OUTDATED`                               | SQL、数据源、规则或 Provider 变更，或 30 分钟预审快照过期，重新运行 AI 预审              |
| `2002`          | `SQL_BATCH_TOO_LARGE`                           | 超过 `32 MiB` / `100,000` 语句 / 单条 `512 KiB` 上限，拆分工单             |
| `2003`          | `SQL_PARSE_FAILED`                              | 方言语法解析失败，按返回的精确行列号修正 SQL                                      |
| `2004`          | `SQL_FINGERPRINT_FAILED`                        | 指纹计算失败或混写 DML 与 DDL，拆分为纯 DML / 纯 DDL 工单                       |
| `2005`          | `SQL_ANONYMIZATION_FAILED`                      | 脱敏失败或检测到原始凭据/密钥，移除敏感信息后重试                                     |
| `2006`          | `TOO_MANY_FINGERPRINTS`                         | 超过单工单 `1,000` 个不同结构指纹组上限，拆分工单                                 |
| `2007`          | `REVIEW_COVERAGE_INCOMPLETE`                    | 预审尚未覆盖全部分组或处于 `partial`，等待或修复元数据后重跑                           |
| `2008`          | `REVIEW_BLOCKED_BY_RISK`                        | 命中强制规则或存在 `critical` 风险阻断提交，根据建议修改 SQL 后重跑预审                  |
| `2009`          | `REVIEW_SCHEMA_INVALID`                         | 模型返回未符合结构化输出 Schema，重试或更换更稳定的 Provider 模型                     |
| `2010`          | `AI_DAILY_BUDGET_EXHAUSTED`                     | 全局单日 AI 预算耗尽，由管理员在 `/admin/review-engine/ai-budget` 调整        |
| `2011`          | `AI_PROVIDER_FAILED`                            | 无可用 AI Provider 或全部调用超时失败，检查 `/admin/review-engine/providers` |
| `2012`          | `REVIEW_TOOL_FAILED`                            | 目标库只读元数据探测失败，检查数据源 `review` 凭据权限与网络连通性                        |
| `2013` / `2014` | `SUBMISSION_GATE_FAILED` / `FLOW_GRANT_REVOKED` | 未通过门禁或流程授权已被撤销                                                |

## `30xx` 审批、执行、`gh-ost` 与结果核验

| 错误码                      | 标识                                                                       | 处理方式                                              |
| :----------------------- | :----------------------------------------------------------------------- | :------------------------------------------------ |
| `3001`                   | `NOT_FROZEN_ACTOR`                                                       | 当前用户不在该阶段冻结审批人或执行人快照中                             |
| `3002`                   | `APPROVAL_ALREADY_DECIDED`                                               | 该审批节点已由同级其他审批人完成决策                                |
| `3003` / `3004`          | `EXECUTION_ALREADY_STARTED` / `EXECUTION_RETRY_FORBIDDEN`                | 执行已启动或当前状态禁止重试                                    |
| `3005`                   | `EXECUTION_RESULT_UNKNOWN`                                               | 提交瞬间网络中断结果未知，冻结执行人查库后人工提交核验结论                     |
| `3006`                   | `EXECUTION_PREFLIGHT_FAILED`                                             | 执行前漂移或凭据预检失败                                      |
| `3007` / `3008` / `3009` | `SCHEDULE_OUT_OF_RANGE` / `OUTSIDE_EXECUTION_WINDOW` / `MISSED_SCHEDULE` | 预约时间非法、超出每周允许执行时段或错过 15 分钟宽限窗口                    |
| `3010`                   | `DATASOURCE_UNAVAILABLE`                                                 | 目标数据源不可达，检查主机、端口与 TLS 证书                          |
| `3011`                   | `GH_OST_UNSUPPORTED`                                                     | 目标表或语句不满足进程内 `gh-ost` 在线改表条件（例如非原生 MySQL 5.7/8.0） |
| `3012`                   | `MANUAL_VERIFICATION_EVIDENCE_REQUIRED`                                  | 核验 `result_unknown` 必须填写非空核验证据说明                  |

## `40xx` 查询、`50xx` 迁移、`60xx` AI 助手与 `70xx` SQL 诊断

| 域                 | 关键错误码与处理                                                                                                                                                                      |
| :---------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`40xx` 查询**     | `4001`/`4002` 未获授权需申请 Query Grant；`4003` 无导出权；`4004`/`4005` 授权被撤销或过期；`4007`/`4011` 仅允许单条只读查询；`4009` 超时需加索引或缩小 `LIMIT`；`4010` 游标失效重新查询                                         |
| **`50xx` v3 迁移**  | `5001` 源库仍有未闭环旧工单；`5002` 未跑 Dry-Run；`5003` 权限映射未全部确认；`5004` 源版本不支持；`5005` 核验不变量失败                                                                                             |
| **`60xx` AI 助手**  | `6001` 超出数据库范畴或请求 `TRUNCATE`/`DROP DATABASE`；`6002` 仅只读权请求了 DML/DDL；`6003` 输入含明文密钥；`6004` 返回 SQL 未过 AST 校验；`6005` 草稿未预审或已修改；`6006` 超上下文预算；`6007` 正在流式输出                       |
| **`70xx` SQL 诊断** | `7001` 仅管理员可访问；`7002` 未启用或缺少只读凭据；`7003` 引擎不支持；`7004` 未开启 `performance_schema`/`pg_stat_statements`；`7005` 只读账号缺统计视图权限；`7006` 手动采样冷却中；`7007` 目标库负载熔断；`7008` 无可用模板或 AI Provider |
