For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /reference/error-codes.md.
  • 简体中文
  • 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 maximumkeyring.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 通用校验、并发、幂等与配额

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

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

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

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

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

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

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