# Frequently asked questions Find causes and solutions for common problems. 排障 · 模块: reference · 使用者 · 部署形态：资料未说明 · 已确认产品版本：资料未说明 · 来源：现有文档 Find the appropriate action based on interface messages, status, or error codes. See [Troubleshooting](https://docs.asktable.com/en/reference/troubleshooting) for system operation issues, and [Error codes](https://docs.asktable.com/en/reference/error-codes) for the complete error code reference. ## Before you begin - Record the exact interface message, or the error code and HTTP status returned by the API. - Record the project name, feature entry, and time of occurrence. - For conversation issues, also include a trace ID: the conversation page has “Copy trace id”. - Determine the scope: one person or multiple people; one project or all projects. ## Key constraints | Item | Value or default | Where to change it | | ------------------------- | ------------------------------------------------------------------------------------------------- | ------------------ | | Interface message source | The frontend selects localized text by error code, rather than using the server's `message` | — | | Where to find error codes | The API response body's `code` field; the interface itself does not display error codes | — | | Additional context | When the server provides a custom message, the displayed text becomes “localized message: detail” | — | | No matching message | The interface displays “Operation failed, please try again later” | — | | Trace ID location | “Copy trace id” on the conversation page | — | | 4xx versus 5xx | 4xx represents business exceptions; 5xx represents server failures | — | ## Troubleshooting ### Conversations and results | Symptom | How to identify it | Action | | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Numbers differ from expectations, but no error appears | The conversation returns normally; results change with a different time range or wording | Check the time range, organization scope, and deduplication rules, then record definitions in field notes under [Table and field notes](https://docs.asktable.com/en/data/semantics) | | Empty result | The interface says “No queryable tables or fields”, with `NO_DATA_TO_QUERY` (HTTP 400) | Confirm a data source is connected and tables have been selected; see [Connect data sources](https://docs.asktable.com/en/data/connect) | | Table not found | `SQL_UNKNOWN_TABLE` (HTTP 400), with the table name and schema in the message | The table was not synchronized or was skipped during selection; select tables again on the data source details page | | Field not found | `SQL_UNKNOWN_FIELD` (HTTP 400), with field and table names in the message | The field may be hidden; see [Hide fields](https://docs.asktable.com/en/data/hidden-fields) | | “The query is too complex. Simplify it and try again” | `CANNOT_HANDLE` (HTTP 400) | Ask in several steps, or narrow the time range first and add conditions gradually | | “Only SELECT queries are allowed” | `SQL_WRITE_NOT_ALLOWED` (HTTP 400) | AskTable runs read queries only; use the data source's own tools for write operations | | “SELECT \* is not allowed. List fields explicitly” | `SQL_SELECT_STAR_NOT_ALLOWED` (HTTP 400) | Name the required fields in the question | | “Table X must be schema-qualified (use schema.table)” | `SQL_UNQUALIFIED_TABLE` (HTTP 400) | Add schema information under [Table and field notes](https://docs.asktable.com/en/data/semantics) | | “The system is busy. Please try again later” | `SERVICE_BUSY` (HTTP 503) | Retry later; if it persists, follow [Troubleshooting](https://docs.asktable.com/en/reference/troubleshooting) | | “Conversation is being processed” | `CHAT_PROCESSING` (HTTP 409) | Wait for the current turn to finish before sending another message | | “The Agent bound to this conversation was deleted. Start a new conversation” | `DATA_AGENT_DELETED` (HTTP 404) | Start a new conversation or select another Agent | | “The role bound to this conversation was deleted. Select another role or start a new conversation” | `ROLE_DELETED` (HTTP 404) | Select a role again or start a new conversation | | “There is not enough conversation content to require compaction yet” | `COMPACTION_NOT_ENOUGH_CONTEXT` (HTTP 400) | Expected behavior; no action needed | | “Context is being compacted. Please wait” | `COMPACTION_IN_PROGRESS` (HTTP 409) | Wait for compaction to finish | | Query never returns results | API timeout, `QUERY_TIMEOUT` (HTTP 504) | Increase the data source's “Query timeout (seconds)”, or “System settings” → “Data sources” → “Global query timeout (seconds)” | ### Data sources and files | Symptom | How to identify it | Action | | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Data source stays at “Analyzing metadata” or “Queued” | The status indicator shows either of these messages | Wait for parsing to finish; if it does not change for a long time, click the status indicator for error details | | Status is “Metadata analysis failed” | The status text is “Metadata analysis failed” | Open the status indicator for error details, then click “Reinitialize” or “Resynchronize” | | Status is “Unavailable” | The status text is “Unavailable” | Click the retry button in the status indicator to reinitialize | | Status is “Synchronizing” | The status text is “Synchronizing”, meaning the data source itself is usable | Wait for synchronization to finish; no need to recreate the data source | | Connection test fails | Dialog title: “Database connection failed”; the body shows the database's original error; `ACCESSOR_CONNECTION_ERROR` (HTTP 400) | Check host, port, account, password, and database name individually; for cloud deployment, confirm the server address in the message has been added to the database allowlist | | “Another refresh is running. Wait for it to finish and try again” | `TABLE_REFRESH_ALREADY_RUNNING` (HTTP 409) | Wait for the current refresh to finish before clicking again | | “Data source metadata is being processed” | `DATASOURCE_META_PROCESSING` (HTTP 409) | Wait for metadata parsing to finish | | “Data source metadata is not ready” | `DATASOURCE_META_NOT_READY` (HTTP 400) | Complete metadata parsing before performing this action | | Excel upload blocked | “Excel file X exceeds the 10 MB limit”, `FILE_TOO_LARGE` (HTTP 400) | Increase “Maximum Excel file size (MB)” or split the file | | Uploaded Excel has too many worksheets | `TOO_MANY_SHEETS` (HTTP 400), with “The Excel file contains too many worksheets” | Split it into multiple files or increase “Maximum sheets per Excel file” | | Upload reports an invalid file format | `FILE_FORMAT_ERROR` (HTTP 400), with “Invalid or unrecognized file format. The file may be corrupted or encrypted. Open it in Excel, verify it, and save a new copy before uploading” | Open it in Excel, save a new copy, and upload again | | CSV exceeds the column limit | “CSV file X contains more than 50 columns” | Increase “Maximum CSV fields” or split columns first | | No tables on the table selection page | “There are no tables in the database” | Confirm the account has read permission on the target database; for Oracle, enter the correct “Service Name” | | Duplicate data source name | `RESOURCE_ALREADY_EXISTS` (HTTP 409) | Use a different data source name | | Cannot change Workbook structure or data | `WORKBOOK_READ_ONLY` (HTTP 403), with “Feishu-synced Workbooks are read-only. Structure and data cannot be modified in AskTable” | Make changes in Feishu | ### Login and permissions | Symptom | How to identify it | Action | | ------------------------------------------------------------------ | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | “Your login has expired. Please log in again” | `TOKEN_EXPIRED` (HTTP 401) | Log in again; include the time of occurrence in a support ticket if it recurs | | “Invalid login credentials” | `TOKEN_INVALID` (HTTP 401) | Log in again; use a new key for API calls | | “Incorrect email or password” | `INVALID_CREDENTIALS` (HTTP 401) | Check the account and password; an administrator can reset it under “Users” on the left | | “User has been disabled” | `USER_DISABLED` (HTTP 403) | Ask an administrator to check the account under “Users” on the left | | “Third-party login failed” | `PROVIDER_AUTH_FAILED` (HTTP 401) | See [Enterprise identity login](https://docs.asktable.com/en/admin/identity) | | “Verification code is invalid or expired” | `VERIFICATION_CODE_INVALID` (HTTP 401) | Request a new verification code | | “The original password is incorrect” | `PASSWORD_MISMATCH` (HTTP 401) | Re-enter the original password | | “Insufficient permissions” | `PERMISSION_DENIED` (HTTP 403) | Have the project owner or administrator confirm project membership and data scopes; see [Permissions and data security](https://docs.asktable.com/en/permissions) | | Can enter a public project, but configuration changes are rejected | `PERMISSION_DENIED` (HTTP 403), with an effective project role of Member | Configuration changes require project owner or administrator permissions; organization roles and project roles are evaluated separately | | “Project is locked” | `PROJECT_LOCKED` (HTTP 423) | Contact a platform administrator to unlock it | | “Project is not empty” | `PROJECT_NOT_EMPTY` (HTTP 403) | Remove the project's data sources, roles, policies, and other resources first | ### Platform and licensing | Symptom | How to identify it | Action | | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | Cannot create a 4th user | “Organization settings” → “Enterprise” in private deployment shows “Trial”, and the user count has reached 3 | See [Commercial licensing](https://docs.asktable.com/en/admin/license) | | Cannot open “Analysis canvas” | “Organization settings” → “Enterprise” in private deployment shows “Trial”, or the tier is p1, p2, or p3 | Use an a1 or a2 tier license | | Accessing any project redirects to a locked page | The page title is “AskTable Enterprise is locked” | See [Commercial licensing](https://docs.asktable.com/en/admin/license) | | “X count has reached the limit (N/M). Delete unused X and try again” | `RESOURCE_QUOTA_EXCEEDED` (HTTP 403) | Delete unused old resources; project resource quotas are enforced only in cloud deployment | | API-Key creation reaches the limit | “Each project can create at most 10 API-Keys” | Delete unused old keys first | | Cannot delete a role | `ROLE_IN_USE` (HTTP 409), with “The role is referenced by N Agent whitelists and cannot be deleted” | Remove the role from the corresponding Agent whitelists first | | Duplicate name | `RESOURCE_ALREADY_EXISTS` (HTTP 409), with “X name already exists” | Use another name | | Page says “Cannot connect to server” | Title: “Cannot connect to server”; body: “Check whether the AskTable backend service is running.”; button: “Retry” | The backend has not started or the network is unreachable; see [Troubleshooting](https://docs.asktable.com/en/reference/troubleshooting) | | Page says “Failed to load user information” | Title: “Failed to load user information”; body: “Unable to load your account information. Log out and log in again.” | Click “Log out” and log in again | | Incorrect platform settings | See the eight sections in “System settings” | [Organizations, projects, and runtime](https://docs.asktable.com/en/admin/organization-runtime) | ### Models and web search | Symptom | How to identify it | Action | | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | “Model group X authentication failed. Check its API key or balance” | `LLM_AUTH_ERROR` (HTTP 400) | See [Configure models](https://docs.asktable.com/en/admin/models) | | “Model group X connection failed” | `LLM_CONNECTION_ERROR` (HTTP 400) | Check the Base URL; for private deployment, also confirm outbound access | | “Model group X service error. Please try again later” | `LLM_ERROR` (HTTP 400) | An upstream error; retry later | | “The AI service returned an invalid response” | `LLM_BAD_RESPONSE` (HTTP 400) | Use another model or adjust its “Provider options” | | “Your input triggered a content safety review. Modify it and try again” | `LLM_CONTENT_FILTERED` (HTTP 400) | Rephrase the question | | “This feature is available only when the official AI proxy channel is configured” | `ASKTABLE_LLM_ONLY` (HTTP 400) | Create an “AskTable official” model group and “Set as default” | | “Web search is not configured. Contact a system administrator to configure it in System settings” | `WEB_SEARCH_NOT_CONFIGURED` (HTTP 400) | Fill in “Base URL”, “API Key”, and “Model” under “System settings” → “Web search” | | Cannot enable an Agent's “Web search” switch | One of the three fields under “System settings” → “Web search” is empty | Complete all fields and save | ### Integrations and APIs | Symptom | How to identify it | Action | | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | No reply when mentioning the bot with `@` in Feishu | See the troubleshooting table in [Connect a Feishu bot](https://docs.asktable.com/en/integrations/feishu) | Check each row on that page | | Embed page says “This embed URL has been disabled.” | `EMBED_DISABLED` (HTTP 403) | Enable the switch in the Agent's “Embed” list | | Embed page says “This website is not allowed to embed this Agent.” | `EMBED_ORIGIN_NOT_ALLOWED` (HTTP 403) | Add the host page's domain to “Allowed domains”; see [Embed the question window in a webpage](https://docs.asktable.com/en/integrations/embed) | | “AI Search index is not enabled” | `VALUE_INDEX_NOT_ENABLED` (HTTP 400) | See [AI indexing](https://docs.asktable.com/en/data/ai-search) | | “AI Search index timed out” | `VALUE_INDEX_TIMEOUT` (HTTP 400) | Retry; if there are too many fields, reduce the indexing field scope first | | “Report generation failed” | `REPORT_FAILED` (HTTP 400) | Create another report; see [Scheduled analysis reports](https://docs.asktable.com/en/integrations/scheduled-reports) | | “Report is being generated” | `REPORT_PROCESSING` (HTTP 409) | Wait for generation to finish | | API, CLI, or MCP returns 401 | Response body: `{"detail": "Insufficient scopes"}` | Use an `admin` API-Key or ask the project “Owner” to grant higher permissions | | API, CLI, or MCP returns 401 with invalid credentials | `TOKEN_INVALID` | Create a new API-Key and configure it again | | API, CLI, or MCP returns 403 with a quota message | `RESOURCE_QUOTA_EXCEEDED` | Delete unused old resources | ### Include when submitting an issue - Project name and feature entry (conversation, data source, analysis canvas, dashboard, embed page, Feishu). - Original question or action steps, and time of occurrence. - Exact interface message, or API error code and HTTP status. - Conversation ID, or the trace ID from “Copy trace id”. - Data scope and time definitions. - Whether it reproduces only for a particular account, role, or data scope. Do not submit passwords, App Secrets, API-Keys, embed tokens, or business data that has not been anonymized. ## Next steps - System-level issues such as services not starting or pages not opening: [Troubleshooting](https://docs.asktable.com/en/reference/troubleshooting) - Complete error code list and corresponding HTTP statuses: [Error codes](https://docs.asktable.com/en/reference/error-codes) - Platform settings and member management: [Organizations, projects, and runtime](https://docs.asktable.com/en/admin/organization-runtime)