Troubleshooting
Frequently asked questions
Find causes and solutions for common problems.
Troubleshooting · Module: reference · Users · Deployment: Not specified · Confirmed product versions: Not specified · Source: Existing documentation
Find the appropriate action based on interface messages, status, or error codes. See Troubleshooting for system operation issues, and 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 |
| 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 |
| 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 |
| “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 |
| “The system is busy. Please try again later” | SERVICE_BUSY (HTTP 503) | Retry later; if it persists, follow 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 |
| “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 |
| 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 |
| 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 |
| “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 |
| 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 |
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 |
| “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 | 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 |
| “AI Search index is not enabled” | VALUE_INDEX_NOT_ENABLED (HTTP 400) | See AI indexing |
| “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 |
| “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
- Complete error code list and corresponding HTTP statuses: Error codes
- Platform settings and member management: Organizations, projects, and runtime