Troubleshooting
Error codes
Look up error codes, interface messages, and actions to take.
Troubleshooting · Module: reference · Users · Deployment: Not specified · Confirmed product versions: Not specified · Source: Existing documentation
Interface messages and API error codes use the same error definitions. Use an error code to look up its HTTP status, interface message, and action to take.
Before you begin
- For interface troubleshooting, record the exact message; users do not need to see error codes.
- For API troubleshooting, check the response body's
codefield together with the HTTP status. API-Key, CLI, and MCP calls all return the same structure. - Get a trace ID: “Copy trace id” on the conversation page copies the identifier for the current turn. Include it in a support ticket; it is more useful than a screenshot.
Key constraints
AskTable business exceptions return this standard structure:
{
"code": "RESOURCE_QUOTA_EXCEEDED",
"message": "Resource quota exceeded for datasources (50/50)",
"params": { "resource_type": "datasources", "current_count": 50, "limit": 50 }
}| Item | Value or default | Where to change it |
|---|---|---|
| Response fields | code, message, params | — |
| Interface message source | The frontend selects localized text by code, rather than using the server's message | — |
| Additional context | When the server provides a custom message, params.detail is appended as “localized message: detail” | — |
| No matching message | The interface displays “Operation failed, please try again later” | — |
| Parameter validation failure | HTTP 422, with code fixed to VALIDATION_ERROR; params.errors contains per-field loc, msg, and type | — |
| 4xx versus 5xx | 4xx represents business exceptions (no alert); 5xx triggers alerts | — |
Troubleshooting
Resources and quotas
| Error code | HTTP | Interface message | Action |
|---|---|---|---|
RESOURCE_ERROR | 400 | “Resource operation failed” | Complete or correct parameters as indicated, then retry |
RESOURCE_NOT_FOUND | 404 | “Resource not found” | The target was deleted; refresh the page and reopen it |
RESOURCE_ALREADY_EXISTS | 409 | “X name already exists” | Use a different name |
RESOURCE_QUOTA_EXCEEDED | 403 | “X count has reached the limit (N/M). Delete unused X and try again” | Delete unused old resources; project resource quotas are enforced only in cloud deployment |
DATABASE_INTEGRITY_ERROR | 409 | “Data integrity conflict” | Remove references first, then retry |
Data sources and metadata
| Error code | HTTP | Interface message | Action |
|---|---|---|---|
ACCESSOR_ERROR | 400 | “Database connection failed” | Check connection details; see Connect data sources |
ACCESSOR_CONNECTION_ERROR | 400 | “Cannot connect to the database” | Check the address, network, and account; for cloud deployment, confirm the allowlist is configured |
DATASOURCE_META_PROCESSING | 409 | “Data source metadata is being processed” | Wait for metadata parsing to complete |
DATASOURCE_META_NOT_READY | 400 | “Data source metadata is not ready” | Complete metadata parsing first |
DATASOURCE_CONFIG_ERROR | 400 | “Data source configuration error” | Check configuration in the data source's “Settings” |
TABLE_REFRESH_ALREADY_RUNNING | 409 | “Another refresh is running. Wait for it to finish and try again” | Wait for the current refresh to finish |
WORKBOOK_NAME_CONFLICT | 409 | “Data source name ‘X’ already exists. Try another name” | Choose another data source name |
WORKBOOK_READ_ONLY | 403 | “Feishu-synced Workbooks are read-only. Structure and data cannot be modified in AskTable” | Make changes in Feishu |
WORKBOOK_FEISHU_SYNC_RUNNING | 409 | “Feishu synchronization is in progress. Please try again later” | Wait for synchronization to finish |
WORKBOOK_FEISHU_SOURCE_NOT_FOUND | 404 | “Feishu synchronization configuration not found” | Create the synchronization configuration again |
WORKBOOK_FEISHU_CREDENTIAL_INVALID | 422 | “Invalid Feishu app credentials. Check the App ID and App Secret” | Re-enter credentials |
WORKBOOK_FEISHU_APP_TOKEN_INVALID | 422 | “Invalid Feishu Bitable App Token or no access” | Confirm the app can access the base |
WORKBOOK_FEISHU_INVALID_URL | 422 | “The link is not recognized as Bitable. Paste the full URL of the Bitable page” | Paste the full URL and retry |
WORKBOOK_FEISHU_TABLE_MISSING | 422 | “Feishu table X does not exist or cannot be accessed” | Select tables again |
WORKBOOK_FEISHU_NO_TABLE_SELECTED | 422 | “Select at least one Feishu table” | Select at least one table |
File uploads
| Error code | HTTP | Interface message | Action |
|---|---|---|---|
DATA_FILE_ERROR | 400 | “File processing error” | Upload again; if it keeps failing, try another file |
FILE_METADATA_PARSE_ERROR | 400 | “Error parsing field X” | Check the column's content and format |
TOO_MANY_SHEETS | 400 | “The Excel file contains too many worksheets” | Split it into multiple files or increase “Maximum sheets per Excel file” |
FILE_RETRIEVAL_FAILED | 400 | “File retrieval failed” | Upload again |
FILE_TOO_LARGE | 400 | “File exceeds the X MB limit” | Increase the corresponding size limit, or compress or split the file |
FILE_TYPE_NOT_SUPPORT | 400 | “File type X is not supported” | Use .xlsx, .xls, or .csv |
FILE_FORMAT_ERROR | 400 | “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” | Save a new copy in Excel, then upload it |
Authentication and users
| Error code | HTTP | Interface message | Action |
|---|---|---|---|
AUTH_ERROR | 401 | “Authentication failed” | Log in again |
TOKEN_EXPIRED | 401 | “Your login has expired. Please log in again” | Log in again |
TOKEN_INVALID | 401 | “Invalid login credentials” | Log in again; use a new key for API calls |
INVALID_CREDENTIALS | 401 | “Incorrect email or password” | Check the account and password |
PROVIDER_AUTH_FAILED | 401 | “Third-party login failed” | See Enterprise identity login |
PASSWORD_MISMATCH | 401 | “The original password is incorrect” | Re-enter the original password |
USER_DISABLED | 403 | “User has been disabled” | Ask an administrator to manage the account under “Users” on the left |
VERIFICATION_CODE_INVALID | 401 | “Verification code is invalid or expired” | Request a new verification code |
Permissions and the semantic layer
| Error code | HTTP | Interface message | Action |
|---|---|---|---|
PERMISSION_DENIED | 403 | “Insufficient permissions” | Add project membership or data scope; see Permissions and data security |
SEMANTIC_WRITE_PERMISSION_DENIED | 403 | “No permission to edit the semantic layer. Administrator permissions are required” | Have the project owner or project administrator perform the action |
SEMANTIC_WRITE_ROLE_CONFLICT | 400 | “Semantic layer writing cannot be used with a conversation role” | Clear the conversation role before enabling writing |
SEMANTIC_VALIDATION_FAILED | 400 | “Semantic layer validation failed. Cannot export dbt YAML” | Fix the validation issues before exporting |
SEMANTIC_EXPORT_FAILED | 400 | “dbt YAML export failed” | Correct the semantic layer and retry |
ROLE_IN_USE | 409 | “The role is referenced by N Agent whitelists and cannot be deleted” | Remove the role from the corresponding Agent whitelists first |
Conversations and queries
| Error code | HTTP | Interface message | Action |
|---|---|---|---|
CHAT_ERROR | 400 | “Conversation error” | Send again; if failures continue, submit a support ticket with the trace ID |
NO_DATA_TO_QUERY | 400 | “No queryable tables or fields” | Confirm a data source is connected and tables have been selected |
CANNOT_HANDLE | 400 | “The query is too complex. Simplify it and try again” | Ask in several steps |
SQL_UNKNOWN_TABLE | 400 | “Table X (schema Y) was not found in the data source” | Select tables again on the data source details page |
SQL_UNKNOWN_FIELD | 400 | “Field Y was not found in table X” | The field may be hidden; see Hide fields |
SQL_SELECT_STAR_NOT_ALLOWED | 400 | “SELECT * is not allowed. List fields explicitly” | Name the fields in your question |
SQL_WRITE_NOT_ALLOWED | 400 | “Only SELECT queries are allowed” | Use read queries only |
SQL_UNQUALIFIED_TABLE | 400 | “Table X must be schema-qualified (use schema.table)” | Add schema information under Table and field notes |
CHAT_PROCESSING | 409 | “Conversation is being processed” | Wait for the current turn to finish |
SERVICE_BUSY | 503 | “The system is busy. Please try again later” | Retry later |
DATA_AGENT_DELETED | 404 | “The Agent bound to this conversation was deleted. Start a new conversation” | Start a new conversation |
ROLE_DELETED | 404 | “The role bound to this conversation was deleted. Select another role or start a new conversation” | Select a role again or start a new conversation |
COMPACTION_NOT_SUPPORTED | 400 | “This conversation type does not support context compaction” | Context compaction is unavailable for this conversation type; this is expected |
COMPACTION_IN_PROGRESS | 409 | “Context is being compacted. Please wait” | Wait for compaction to finish |
COMPACTION_NOT_ENOUGH_CONTEXT | 400 | “There is not enough conversation content to require compaction yet” | Expected behavior; no action needed |
FEEDBACK_NOT_ALLOWED | 400 | “This conversation does not support feedback” | Only Agent conversations support feedback |
FEEDBACK_TARGET_INVALID | 404 | “The target feedback message does not exist” | Refresh the page and submit again |
FEEDBACK_LOGIN_REQUIRED | 403 | “Please log in before submitting feedback” | Log in and submit |
Models and web search
| Error code | HTTP | Interface message | Action |
|---|---|---|---|
LLM_ERROR | 400 | “Model group X service error. Please try again later” | An upstream error; retry later and check upstream status if failures continue |
LLM_CONNECTION_ERROR | 400 | “Model group X connection failed” | Check the Base URL and outbound access; see Configure models |
LLM_BAD_RESPONSE | 400 | “The AI service returned an invalid response” | Try another model or adjust its “Provider options” |
LLM_AUTH_ERROR | 400 | “Model group X authentication failed. Check its API key or balance” | Re-enter the API Key or top up |
LLM_AGENT_BAD_RESPONSE | 400 | “The AI Agent returned a response that could not be parsed” | Send again; change models if failures continue |
LLM_CONTENT_FILTERED | 400 | “Your input triggered a content safety review. Modify it and try again” | Rephrase the question; the review is upstream |
ASKTABLE_LLM_ONLY | 400 | “This feature is available only when the official AI proxy channel is configured” | Create an “AskTable official” model group and make it the default |
WEB_SEARCH_NOT_CONFIGURED | 400 | “Web search is not configured. Contact a system administrator to configure it in System settings” | Complete all three fields in “System settings” → “Web search” |
Embedding, reports, and indexes
| Error code | HTTP | Interface message | Action |
|---|---|---|---|
EMBED_ORIGIN_NOT_ALLOWED | 403 | “This website is not allowed to embed this Agent.” | Add the host page's domain to “Allowed domains” |
EMBED_DISABLED | 403 | “This embed URL has been disabled.” | Enable the switch in the Agent's “Embed” list |
REPORT_PROCESSING | 409 | “Report is being generated” | Wait for generation to finish |
REPORT_FAILED | 400 | “Report generation failed” | Create the report again |
REPORT_STATUS_MISMATCH | 400 | “Report status mismatch: expected X, current Y” | Refresh and retry |
VALUE_INDEX_ERROR | 400 | “AI Search index error” | Rebuild the index; see AI indexing |
VALUE_INDEX_TIMEOUT | 400 | “AI Search index timed out” | Retry; if there are too many fields, reduce the indexing scope first |
VALUE_INDEX_NOT_ENABLED | 400 | “AI Search index is not enabled” | See AI indexing |
Projects, licensing, and billing
| Error code | HTTP | Interface message | Action |
|---|---|---|---|
PROJECT_LOCKED | 423 | “Project is locked” | Contact a platform administrator to unlock it |
PROJECT_NOT_EMPTY | 403 | “Project is not empty” | Remove the project's resources first |
LICENSE_INVALID | 400 | “License is invalid or expired” | See Commercial licensing |
ORDER_ALREADY_PAID | 409 | “Order has already been paid” | Do not pay again |
WECHAT_PAY_ERROR | 400 | “WeChat Pay error” | Place the order again |
CONCURRENT_DEDUCTION_CONFLICT | 409 | “Operation conflict. Please retry” | Retry |
REDEEM_CODE_DISABLED | 409 | “This redemption code has been revoked” | Use another redemption code |
REDEEM_CODE_EXPIRED | 410 | “This redemption code has expired” | Use another redemption code |
REDEEM_CODE_INVALID | 400 | “Invalid redemption code” | Check that the redemption code is complete |
External services and the system
| Error code | HTTP | Interface message | Action |
|---|---|---|---|
EXTERNAL_API_ERROR | 500 | “External service call failed” | Retry later |
AI_PROXY_ERROR | 500 | “AI proxy service error” | Retry later |
CRM_API_ERROR | 500 | “CRM service error” | Retry later |
SMS_ERROR | 500 | “SMS service error” | Check SMS gateway configuration in “System settings” → “Phone number binding” |
ASR_ERROR | 500 | “Speech recognition service error” | Retry; try another audio clip if failures continue |
NOT_SUPPORT | 400 | “Feature X is not enabled or supported” | Confirm the feature is available for the current deployment type and license |
VALIDATION_ERROR | 400 or 422 | “Data validation failed” | Correct parameters as indicated; request body validation failure returns 422 |
PARAMETER_ERROR | 400 | “Invalid parameter X” | Correct the parameter |
CONFIG_ERROR | 400 | “Configuration error: X” | Change configuration as indicated |
INTERNAL_ERROR | 500 | “Internal server error” | Retry later; submit a support ticket with the trace ID if failures continue |
Error codes without matching messages
The following codes are defined on the server and return their corresponding HTTP status, but have no matching Chinese frontend messages. The interface shows the fallback “Operation failed, please try again later”. Use code when troubleshooting API calls.
| Error code | HTTP | Interface message | Action |
|---|---|---|---|
ACCESSOR_AUTH_ERROR | 400 | “Operation failed, please try again later” | Incorrect database account or password |
ACCESSOR_DATABASE_NOT_FOUND | 400 | “Operation failed, please try again later” | Incorrect database name, or the database does not exist |
ACCESSOR_NETWORK_ERROR | 400 | “Operation failed, please try again later” | No network connectivity from the AskTable server to the database |
ACCESSOR_PERMISSION_DENIED | 400 | “Operation failed, please try again later” | Insufficient database account permissions |
ACCESSOR_SQL_ERROR | 400 | “Operation failed, please try again later” | Database SQL execution error |
ACCESSOR_ENTERPRISE_ONLY | 403 | “Operation failed, please try again later” | This data source type requires enterprise licensing |
TABLE_NOT_FOUND_IN_DATASOURCE | 404 | “Operation failed, please try again later” | The table was deleted or renamed in the database |
DATASOURCE_META_ALREADY_INITIALIZED | 409 | “Operation failed, please try again later” | Metadata is already initialized; use update instead of initialization |
QUERY_TIMEOUT | 504 | “Operation failed, please try again later” | Query timed out; increase “Global query timeout (seconds)” |
FILE_DOWNLOAD_TIMEOUT | 504 | “Operation failed, please try again later” | File download timed out; retry |
FILE_RETRIEVAL_TRANSIENT | 503 | “Operation failed, please try again later” | Temporary file storage failure; retry |
TASK_TIMEOUT | 504 | “Operation failed, please try again later” | Background task timed out; retry |
LLM_TIMEOUT | 400 | “Operation failed, please try again later” | Model request timed out; retry or use a faster model |
LLM_RATE_LIMIT | 400 | “Operation failed, please try again later” | Upstream rate limiting; retry later |
LLM_PROVIDER_INTERNAL_ERROR | 400 | “Operation failed, please try again later” | Internal upstream SDK error; retry later |
SHARE_DISABLED | 403 | “Operation failed, please try again later” | Sharing is disabled or expired |
CODE_EXECUTION_ERROR | 400 | “Operation failed, please try again later” | Python sandbox execution failed; rephrase the question |
STUCK_REFRESH_RECOVERED | 500 | “Operation failed, please try again later” | A refresh task recovered automatically after interruption; retry |
SMS_GATEWAY_REJECTED | 502 | “Operation failed, please try again later” | The SMS gateway rejected the request; check the phone number and gateway account |
WORKBOOK_* family | Mostly 422, with some 400, 403, 404, 409, 413 | “Operation failed, please try again later” | Workbook validation failed for field types, row counts, batches, import mappings, etc.; use the server's message to identify the cause |
Next steps
- Identify issues quickly by symptom: Frequently asked questions
- Services will not start or pages will not open: Troubleshooting
- Licensing errors: Commercial licensing