开始前
- 先记下界面提示原文，或者接口返回的错误码与 HTTP 状态。
- 记下项目名称、功能入口和发生时间。
- 对话里的问题再补一个 trace id：对话页有「复制 trace id」。
- 判断范围：只有一个人受影响还是一批人；只有一个项目还是全部项目。
关键约束
| 项目 | 值或默认 | 在哪里改 |
|---|---|---|
| 界面提示来源 | 前端按错误码取本地化文案，不使用服务端 message | — |
| 错误码可见位置 | 接口响应体的 code 字段；界面本身不显示错误码 | — |
| 追加的上下文 | 服务端给了自定义消息时，提示会变成「本地化文案：detail」 | — |
| 没有对应文案时 | 界面统一显示「操作失败，请稍后重试」 | — |
| trace id 位置 | 对话页的「复制 trace id」 | — |
| 4xx 与 5xx | 4xx 是业务异常，5xx 才代表服务端故障 | — |
出问题怎么判断
对话与结果
| 现象 | 判定条件 | 处理 |
|---|---|---|
| 数字和预期不一致，但没有任何报错 | 对话正常返回；换时间范围或换个问法后结果变化 | 先核对时间范围、组织范围和去重规则，再到表与字段备注把口径写进字段备注 |
| 结果为空 | 界面提示「没有可查询的数据表或字段」，错误码 NO_DATA_TO_QUERY（HTTP 400） | 确认数据源已接入并选过表，见连接数据源 |
| 说找不到表 | 错误码 SQL_UNKNOWN_TABLE（HTTP 400），提示里带表名和 schema | 表没同步进来，或选表时跳过了；到数据源详情页重新选表 |
| 说找不到字段 | 错误码 SQL_UNKNOWN_FIELD（HTTP 400），提示里带字段名和表名 | 字段可能被隐藏，见隐藏字段 |
| 提示「查询过于复杂，请简化后重试」 | 错误码 CANNOT_HANDLE（HTTP 400） | 拆成几步问，或先缩小时间范围再逐步加条件 |
| 提示「只允许 SELECT 查询」 | 错误码 SQL_WRITE_NOT_ALLOWED（HTTP 400） | AskTable 只做读查询，写操作走数据源自己的工具 |
| 提示「不允许 SELECT *，请显式列出字段」 | 错误码 SQL_SELECT_STAR_NOT_ALLOWED（HTTP 400） | 问题里点名要哪些字段 |
| 提示「表 X 必须限定 schema（用 schema.table）」 | 错误码 SQL_UNQUALIFIED_TABLE（HTTP 400） | 到表与字段备注补 schema 信息 |
| 提示「系统繁忙，请稍后重试」 | 错误码 SERVICE_BUSY（HTTP 503） | 稍后重试；持续出现时走故障排查 |
| 提示「对话正在处理中」 | 错误码 CHAT_PROCESSING（HTTP 409） | 等当前这轮结束再发 |
| 提示「当前会话绑定的智能体已被删除，请新建会话」 | 错误码 DATA_AGENT_DELETED（HTTP 404） | 新建对话，或重新选一个智能体 |
| 提示「当前会话绑定的角色已被删除，请重新选择角色或新建会话」 | 错误码 ROLE_DELETED（HTTP 404） | 重新选角色或新建对话 |
| 提示「对话内容还不够多，暂时无需压缩」 | 错误码 COMPACTION_NOT_ENOUGH_CONTEXT（HTTP 400） | 属预期，不用处理 |
| 提示「上下文正在压缩中，请稍候」 | 错误码 COMPACTION_IN_PROGRESS（HTTP 409） | 等压缩结束 |
| 查询一直不返回结果 | 接口超时，错误码 QUERY_TIMEOUT（HTTP 504） | 放宽数据源的「查询超时（秒）」，或调大「系统设置」→「数据源」→「全局查询超时（秒）」 |
数据源与文件
| 现象 | 判定条件 | 处理 |
|---|---|---|
| 数据源状态一直停在「正在分析元数据」或「排队中」 | 数据源状态指示器文字就是这两项 | 等解析完成；长时间不动就点状态指示器看错误详情 |
| 状态显示「分析元数据失败」 | 状态文字是「分析元数据失败」 | 点开状态指示器看错误详情，再点「重新初始化」或「重新同步」 |
| 状态显示「不可用」 | 状态文字是「不可用」 | 点状态指示器里的重试按钮重新初始化 |
| 状态显示「同步中」 | 状态文字是「同步中」，说明数据源本身可用 | 等同步结束，不用重建数据源 |
| 连接测试没过 | 弹窗标题「数据库连接失败」，正文是数据库返回的原始错误；错误码 ACCESSOR_CONNECTION_ERROR（HTTP 400） | 逐项核对主机、端口、账号、密码、库名；云端部署时确认已把提示里的服务器地址加进数据库白名单 |
| 提示「另一次刷新正在进行中，请等其完成再试」 | 错误码 TABLE_REFRESH_ALREADY_RUNNING（HTTP 409） | 等本次刷新结束再点 |
| 提示「数据源元数据正在处理中」 | 错误码 DATASOURCE_META_PROCESSING（HTTP 409） | 等元数据解析完成 |
| 提示「数据源元数据未就绪」 | 错误码 DATASOURCE_META_NOT_READY（HTTP 400） | 先完成元数据解析，再执行这个操作 |
| 上传 Excel 被拦 | 界面提示「Excel文件 X 超过10MB限制」，错误码 FILE_TOO_LARGE（HTTP 400） | 调大「Excel 最大文件大小（MB）」或拆分文件 |
| 上传的 Excel 提示工作表过多 | 错误码 TOO_MANY_SHEETS（HTTP 400），界面提示「Excel 文件包含过多工作表」 | 拆成多个文件，或调大「Excel 最大 Sheet 数」 |
| 上传文件提示格式无效 | 错误码 FILE_FORMAT_ERROR（HTTP 400），界面提示「文件格式无效或无法识别，文件可能已损坏或被加密，请用 Excel 打开确认后另存为再上传」 | 用 Excel 打开后另存为再上传 |
| CSV 提示列数超限 | 界面提示「CSV文件 X 包含超过50列」 | 调大「CSV 最大字段数」或先拆列 |
| 选表页一张表都没有 | 提示「数据库中没有任何库表」 | 确认账号对目标库有读权限；Oracle 要填对「Service Name」 |
| 数据源名称重复 | 错误码 RESOURCE_ALREADY_EXISTS（HTTP 409） | 换一个数据源名称 |
| 工作簿改不了结构或数据 | 错误码 WORKBOOK_READ_ONLY（HTTP 403），界面提示「飞书同步工作簿为只读，不能在 AskTable 内修改结构或数据」 | 改到飞书侧改 |
登录与权限
| 现象 | 判定条件 | 处理 |
|---|---|---|
| 提示「登录已过期，请重新登录」 | 错误码 TOKEN_EXPIRED（HTTP 401） | 重新登录；反复出现时带上发生时间提工单 |
| 提示「登录凭证无效」 | 错误码 TOKEN_INVALID（HTTP 401） | 重新登录；用 API 调用的换成新 key |
| 提示「邮箱或密码错误」 | 错误码 INVALID_CREDENTIALS（HTTP 401） | 核对账号密码；管理员可在左侧「用户」里重置 |
| 提示「用户已被禁用」 | 错误码 USER_DISABLED（HTTP 403） | 找管理员在左侧「用户」里查看该账号 |
| 提示「第三方登录失败」 | 错误码 PROVIDER_AUTH_FAILED（HTTP 401） | 见企业身份登录 |
| 提示「验证码无效或已过期」 | 错误码 VERIFICATION_CODE_INVALID（HTTP 401） | 重新获取验证码 |
| 提示「原密码不正确」 | 错误码 PASSWORD_MISMATCH（HTTP 401） | 重填原密码 |
| 提示「权限不足」 | 错误码 PERMISSION_DENIED（HTTP 403） | 让项目「所有者」把该账号加进项目并补数据范围，见权限与数据安全 |
| 在公开项目里点配置被弹回 | 错误码 VIEWER_READONLY，界面提示「当前为所有人可见的公开项目，不能修改资源配置」 | 切到自己的私有项目再操作 |
| 提示「项目已锁定」 | 错误码 PROJECT_LOCKED（HTTP 423） | 联系平台管理员解除锁定 |
| 提示「项目不为空」 | 错误码 PROJECT_NOT_EMPTY（HTTP 403） | 先清空项目内的数据源、角色、策略等资源 |
平台与授权
| 现象 | 判定条件 | 处理 |
|---|---|---|
| 建不了第 4 个用户 | 头像菜单第一项显示「体验版」，且用户数已到 3 | 见商业授权 |
| 「分析画卷」打不开 | 头像菜单第一项显示「体验版」，或层级是 p1、p2、p3 | 换 a1 或 a2 层级的许可证 |
| 访问任意项目都被跳到锁定页 | 界面标题是「AskTable 企业版已锁定」 | 见商业授权 |
| 提示「X数量已达上限（N/M），请删除不需要的X后重试」 | 错误码 RESOURCE_QUOTA_EXCEEDED（HTTP 403） | 删掉不用的旧资源；项目资源配额只在云端部署执行 |
| 建 API-Key 到上限 | 界面提示「每个项目最多允许创建 10 个 API-Key」 | 先删掉不用的旧 key |
| 角色删不掉 | 错误码 ROLE_IN_USE（HTTP 409），界面提示「角色正被 N 个智能体白名单引用，无法删除」 | 先从相关智能体的白名单里移除该角色 |
| 名称重复 | 错误码 RESOURCE_ALREADY_EXISTS（HTTP 409），界面提示「X名称已存在」 | 换一个名称 |
| 页面提示「无法连接服务器」 | 页面标题是「无法连接服务器」，正文「请检查 AskTable 后端服务是否正在运行。」，按钮「重试」 | 后端没起来或网络不通，见故障排查 |
| 页面提示「用户信息加载失败」 | 页面标题是「用户信息加载失败」，正文「无法加载您的账户信息，请退出后重新登录。」 | 点「退出登录」后重新登录 |
| 平台参数不对 | 见「系统设置」里的八个区块 | 组织、项目与运行 |
模型与联网搜索
| 现象 | 判定条件 | 处理 |
|---|---|---|
| 提示「模型组 X 认证失败，请检查该模型组的 API 密钥或余额」 | 错误码 LLM_AUTH_ERROR（HTTP 400） | 见配置大模型 |
| 提示「模型组 X 连接失败」 | 错误码 LLM_CONNECTION_ERROR（HTTP 400） | 核对 Base URL；私有部署再确认能出网 |
| 提示「模型组 X 服务异常，请稍后重试」 | 错误码 LLM_ERROR（HTTP 400） | 上游异常，稍后重试 |
| 提示「AI 服务返回了无效响应」 | 错误码 LLM_BAD_RESPONSE（HTTP 400） | 换一个模型，或调整该模型的「供应商选项」 |
| 提示「输入内容触发了内容安全审查，请修改后重试」 | 错误码 LLM_CONTENT_FILTERED（HTTP 400） | 换问法 |
| 提示「此功能仅在配置官方 AI 代理通道时可用」 | 错误码 ASKTABLE_LLM_ONLY（HTTP 400） | 新建一个「AskTable 官方」类型的模型组并「设为默认」 |
| 提示「联网搜索未配置，请联系系统管理员在系统设置中配置」 | 错误码 WEB_SEARCH_NOT_CONFIGURED（HTTP 400） | 到「系统设置」→「联网搜索」把「Base URL」「API Key」「模型」三项填齐 |
| 智能体的「联网搜索」开关打不开 | 「系统设置」→「联网搜索」三项里有一项为空 | 填齐后保存 |
集成与接口
| 现象 | 判定条件 | 处理 |
|---|---|---|
飞书里 @ 机器人没回复 | 见接入飞书机器人的判定表 | 按该页逐行对照 |
| 嵌入页提示「该嵌入地址已被停用。」 | 错误码 EMBED_DISABLED（HTTP 403） | 到智能体「嵌入」列表把开关打开 |
| 嵌入页提示「该网站未被允许嵌入此智能体。」 | 错误码 EMBED_ORIGIN_NOT_ALLOWED（HTTP 403） | 把宿主页域名加进「允许域名」，见把问数窗口嵌进网页 |
| 提示「AI 搜索索引未启用」 | 错误码 VALUE_INDEX_NOT_ENABLED（HTTP 400） | 见AI 索引 |
| 提示「AI 搜索索引超时」 | 错误码 VALUE_INDEX_TIMEOUT（HTTP 400） | 重试；字段太多就先缩小建立索引的字段范围 |
| 提示「报告生成失败」 | 错误码 REPORT_FAILED（HTTP 400） | 重新创建一份报告，见定时分析报告 |
| 提示「报告正在生成中」 | 错误码 REPORT_PROCESSING（HTTP 409） | 等生成完成 |
| API、CLI 或 MCP 返回 401 | 响应体是 {"detail": "Insufficient scopes"} | 换用 admin 类型的 API-Key，或找项目「所有者」提权 |
| API、CLI 或 MCP 返回 401 且提示凭证无效 | 错误码 TOKEN_INVALID | 重新创建一个 API-Key 再配 |
| API、CLI 或 MCP 返回 403 且提示配额 | 错误码 RESOURCE_QUOTA_EXCEEDED | 删掉不用的旧资源 |
提交问题时附上
- 项目名称和功能入口（对话、数据源、画卷、数据看板、嵌入页、飞书）。
- 原始问题或操作步骤，以及发生时间。
- 界面提示原文，或接口返回的错误码与 HTTP 状态。
- 会话 ID，或「复制 trace id」拿到的 trace id。
- 数据范围和时间口径。
- 是否只有某个账号、某个角色或某个数据范围会复现。