# 常见问题

查找常见问题的原因和处理方法。

根据界面提示、状态或错误码查找对应的处理方法。系统运行问题见[故障排查](https://docs.asktable.com/reference/troubleshooting)，完整错误码见[错误码](https://docs.asktable.com/reference/error-codes)。

## 开始前

- 先记下界面提示原文，或者接口返回的错误码与 HTTP 状态。
- 记下项目名称、功能入口和发生时间。
- 对话里的问题再补一个 trace id：对话页有「复制 trace id」。
- 判断范围：只有一个人受影响还是一批人；只有一个项目还是全部项目。

## 关键约束

| 项目          | 值或默认                            | 在哪里改 |
| ----------- | ------------------------------- | ---- |
| 界面提示来源      | 前端按错误码取本地化文案，不使用服务端 `message`   | —    |
| 错误码可见位置     | 接口响应体的 `code` 字段；界面本身不显示错误码     | —    |
| 追加的上下文      | 服务端给了自定义消息时，提示会变成「本地化文案：detail」 | —    |
| 没有对应文案时     | 界面统一显示「操作失败，请稍后重试」              | —    |
| trace id 位置 | 对话页的「复制 trace id」               | —    |
| 4xx 与 5xx   | 4xx 是业务异常，5xx 才代表服务端故障          | —    |

## 出问题怎么判断

### 对话与结果

| 现象                                  | 判定条件                                                | 处理                                                                              |
| ----------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------- |
| 数字和预期不一致，但没有任何报错                    | 对话正常返回；换时间范围或换个问法后结果变化                              | 先核对时间范围、组织范围和去重规则，再到[表与字段备注](https://docs.asktable.com/data/semantics)把口径写进字段备注 |
| 结果为空                                | 界面提示「没有可查询的数据表或字段」，错误码 `NO_DATA_TO_QUERY`（HTTP 400） | 确认数据源已接入并选过表，见[连接数据源](https://docs.asktable.com/data/connect)                   |
| 说找不到表                               | 错误码 `SQL_UNKNOWN_TABLE`（HTTP 400），提示里带表名和 schema    | 表没同步进来，或选表时跳过了；到数据源详情页重新选表                                                      |
| 说找不到字段                              | 错误码 `SQL_UNKNOWN_FIELD`（HTTP 400），提示里带字段名和表名        | 字段可能被隐藏，见[隐藏字段](https://docs.asktable.com/data/hidden-fields)                   |
| 提示「查询过于复杂，请简化后重试」                   | 错误码 `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）               | 到[表与字段备注](https://docs.asktable.com/data/semantics)补 schema 信息                  |
| 提示「系统繁忙，请稍后重试」                      | 错误码 `SERVICE_BUSY`（HTTP 503）                        | 稍后重试；持续出现时走[故障排查](https://docs.asktable.com/reference/troubleshooting)          |
| 提示「对话正在处理中」                         | 错误码 `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）               | 见[企业身份登录](https://docs.asktable.com/admin/identity)                       |
| 提示「验证码无效或已过期」   | 错误码 `VERIFICATION_CODE_INVALID`（HTTP 401）          | 重新获取验证码                                                                   |
| 提示「原密码不正确」      | 错误码 `PASSWORD_MISMATCH`（HTTP 401）                  | 重填原密码                                                                     |
| 提示「权限不足」        | 错误码 `PERMISSION_DENIED`（HTTP 403）                  | 让项目负责人或管理员确认项目成员身份和数据范围，见[权限与数据安全](https://docs.asktable.com/permissions) |
| 能进入公开项目，但修改配置被拒 | 错误码 `PERMISSION_DENIED`（HTTP 403），当前有效项目角色是 Member | 修改配置需要项目负责人或管理员权限；组织角色与项目角色分别判断                                           |
| 提示「项目已锁定」       | 错误码 `PROJECT_LOCKED`（HTTP 423）                     | 联系平台管理员解除锁定                                                               |
| 提示「项目不为空」       | 错误码 `PROJECT_NOT_EMPTY`（HTTP 403）                  | 先清空项目内的数据源、角色、策略等资源                                                       |

### 平台与授权

| 现象                           | 判定条件                                                    | 处理                                                                      |
| ---------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------- |
| 建不了第 4 个用户                   | 私有部署的「组织设置」→「企业版」显示「体验版」，且用户数已到 3                       | 见[商业授权](https://docs.asktable.com/admin/license)                        |
| 「分析画卷」打不开                    | 私有部署的「组织设置」→「企业版」显示「体验版」，或层级是 p1、p2、p3                  | 换 a1 或 a2 层级的许可证                                                        |
| 访问任意项目都被跳到锁定页                | 界面标题是「AskTable 企业版已锁定」                                  | 见[商业授权](https://docs.asktable.com/admin/license)                        |
| 提示「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 后端服务是否正在运行。」，按钮「重试」      | 后端没起来或网络不通，见[故障排查](https://docs.asktable.com/reference/troubleshooting) |
| 页面提示「用户信息加载失败」               | 页面标题是「用户信息加载失败」，正文「无法加载您的账户信息，请退出后重新登录。」                | 点「退出登录」后重新登录                                                            |
| 平台参数不对                       | 见「系统设置」里的八个区块                                           | [组织、项目与运行](https://docs.asktable.com/admin/organization-runtime)        |

### 模型与联网搜索

| 现象                                | 判定条件                                      | 处理                                               |
| --------------------------------- | ----------------------------------------- | ------------------------------------------------ |
| 提示「模型组 X 认证失败，请检查该模型组的 API 密钥或余额」 | 错误码 `LLM_AUTH_ERROR`（HTTP 400）            | 见[配置大模型](https://docs.asktable.com/admin/models) |
| 提示「模型组 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」「模型」三项填齐       |
| 智能体的「联网搜索」开关打不开                   | 「系统设置」→「联网搜索」三项里有一项为空                     | 填齐后保存                                            |

### 集成与接口

| 现象                           | 判定条件                                                          | 处理                                                                           |
| ---------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| 飞书里 `@` 机器人没回复               | 见[接入飞书机器人](https://docs.asktable.com/integrations/feishu)的判定表 | 按该页逐行对照                                                                      |
| 嵌入页提示「该嵌入地址已被停用。」            | 错误码 `EMBED_DISABLED`（HTTP 403）                                | 到智能体「嵌入」列表把开关打开                                                              |
| 嵌入页提示「该网站未被允许嵌入此智能体。」        | 错误码 `EMBED_ORIGIN_NOT_ALLOWED`（HTTP 403）                      | 把宿主页域名加进「允许域名」，见[把问数窗口嵌进网页](https://docs.asktable.com/integrations/embed)    |
| 提示「AI 搜索索引未启用」               | 错误码 `VALUE_INDEX_NOT_ENABLED`（HTTP 400）                       | 见[AI 索引](https://docs.asktable.com/data/ai-search)                           |
| 提示「AI 搜索索引超时」                | 错误码 `VALUE_INDEX_TIMEOUT`（HTTP 400）                           | 重试；字段太多就先缩小建立索引的字段范围                                                         |
| 提示「报告生成失败」                   | 错误码 `REPORT_FAILED`（HTTP 400）                                 | 重新创建一份报告，见[定时分析报告](https://docs.asktable.com/integrations/scheduled-reports) |
| 提示「报告正在生成中」                  | 错误码 `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。
- 数据范围和时间口径。
- 是否只有某个账号、某个角色或某个数据范围会复现。

不要提交密码、App Secret、API-Key、嵌入 token 或未脱敏的业务数据。

## 下一步

- 服务起不来、页面打不开这类系统级问题：[故障排查](https://docs.asktable.com/reference/troubleshooting)
- 想看错误码的完整清单和对应 HTTP 状态：[错误码](https://docs.asktable.com/reference/error-codes)
- 平台参数与成员管理：[组织、项目与运行](https://docs.asktable.com/admin/organization-runtime)