Troubleshooting
Troubleshooting
Troubleshoot service startup, page access, and data connections.
Troubleshooting · Module: reference · Users · Deployment: Not specified · Confirmed product versions: Not specified · Source: Existing documentation
Use this page to troubleshoot system issues such as service startup, page access, and data connections. See Frequently asked questions for issues using individual features.
Record the current state before restarting:
- Record the project name, feature entry, time of occurrence, and exact interface message (or API error code and HTTP status).
- Include a trace ID if available: “Copy trace id” on the conversation page.
- Determine the scope: one person or multiple people; one project or all projects. This directly determines where to investigate.
- For private deployment, first confirm you can log in to the host, run
docker compose ps, and inspect container logs.
| Item | Value or default | Where to change it |
|---|
| Private deployment servers, networking, backups, upgrades, and logs | Your team's responsibility | — |
| Images and version releases | AskTable's responsibility | — |
| Public ports | Only the main service exposes 8000; other containers do not map host ports | ports in docker-compose.yaml |
| Backend health check | curl -sS http://127.0.0.1:8000/api/v1/version returns JSON | — |
| Current version | Avatar → “System settings” → “About” on the left → “System version” | — |
| Business exceptions and failures | 4xx represents business exceptions; 5xx represents server failures | — |
| API error structure | code, message, params; insufficient scope returns {"detail": "Insufficient scopes"} | — |
| Symptom | How to identify it | Action |
|---|
| Page keeps loading or is blank | curl -sS http://127.0.0.1:8000/api/v1/version does not return JSON | The backend has not started; check container status using the troubleshooting table in Private deployment (Docker) |
| Page title is “Cannot connect to server” | Body: “Check whether the AskTable backend service is running.”; button: “Retry” | Confirm the main service container is running and the browser can reach the site |
| Page title is “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; include the time of occurrence in a support ticket if it recurs |
| No version number on the “About” page | The “System version” card has no version string | The container has not started or version injection failed; inspect images with docker compose images instead |
| Links in email or Feishu notifications do not work | “System settings” → “General” → “Frontend URL” still uses the default | Set it to the actual domain and save |
| Login immediately returns to the login page | API returns 401 with TOKEN_EXPIRED or TOKEN_INVALID | Log in again; include the time of occurrence in a support ticket if it recurs |
| Accessing any project redirects to the locked page | Page title: “AskTable Enterprise is locked” | See Commercial licensing |
| Page styling or text resembles an old version | The version on the “About” page does not match the newly deployed image | Frontend static assets and backend versions differ; redeploy and force-refresh the page |
| Symptom | How to identify it | Action |
|---|
| Status stays at “Analyzing metadata” or “Queued” | The data source status indicator text does not change | Open the status indicator for error details; large metadata batches take longer to parse |
| Status is “Metadata analysis failed” | Status text: “Metadata analysis failed” | Click “Reinitialize” or “Resynchronize” in the status indicator |
| Status is “Unavailable” | Status text: “Unavailable” | Click the retry button in the status indicator to reinitialize |
| Connection test fails | Dialog title: “Database connection failed”; the body shows the database's original error | Check host, port, account, password, and database name individually; for cloud deployment, confirm the database allowlist is configured |
| No tables on the table selection page | “There are no tables in the database” | Confirm the account has read access to the target database; for Oracle, enter the correct “Service Name” |
| “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 |
| Some sheets are missing from a file-based data source | The status indicator shows “Some sheets in the following files could not be parsed” | Fix the source file according to each rejection reason and suggested fix, then upload again |
| Symptom | How to identify it | Action |
|---|
| Query never returns results | QUERY_TIMEOUT (HTTP 504) | Increase the timeout under the data source's “Settings” → “Query settings”, or “System settings” → “Data sources” → “Global query timeout (seconds)” |
| “The system is busy. Please try again later” | SERVICE_BUSY (HTTP 503) | Retry later; if it persists, check the main service container's resource usage |
| “Conversation is being processed” | CHAT_PROCESSING (HTTP 409) | Wait for the current turn to finish |
| “Context is being compacted. Please wait” | COMPACTION_IN_PROGRESS (HTTP 409) | Wait for compaction to finish |
| “The Agent bound to this conversation was deleted. Start a new conversation” | DATA_AGENT_DELETED (HTTP 404) | Start a new conversation |
| “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 |
| Model-related error | The error code begins with LLM_ | See the troubleshooting table in Configure models |
| Symptom | How to identify it | Action |
|---|
| “Insufficient permissions” | PERMISSION_DENIED (HTTP 403) | Add the account to the project and grant data scope; 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 the project owner or project administrator; check explicit project roles and the public project's default role |
| User cannot see a project | The project is absent from the left project list | Add the person under Project settings → “Project members” |
| “User has been disabled” | USER_DISABLED (HTTP 403) | Have an administrator manage the account under “Users” on the left |
| API returns 401 | Response body: {"detail": "Insufficient scopes"} | Use an admin API-Key or ask the project “Owner” to grant higher permissions |
| “Project is locked” | PROJECT_LOCKED (HTTP 423) | Contact a platform administrator to unlock it |
| Symptom | How to identify it | Action |
|---|
| Cannot enable an Agent's “Web search” switch | One of the three fields under “System settings” → “Web search” is empty | Complete “Base URL”, “API Key”, and “Model”, then save |
| “Web search is not configured. Contact a system administrator to configure it in System settings” | WEB_SEARCH_NOT_CONFIGURED (HTTP 400) | Same as above |
| “Your input triggered a content safety review. Modify it and try again” | LLM_CONTENT_FILTERED (HTTP 400) | Rephrase the question; the review is upstream, rather than an AskTable block |
| “Test model” fails | “Model X test failed” | See Configure models |
| “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” |
| 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; private deployment must also add the search service container first, as described in Deploy AI Search |
| Scheduled report was not delivered | REPORT_FAILED (HTTP 400) | Create the report again; see Scheduled analysis reports |
| API returns 403 with a quota message | RESOURCE_QUOTA_EXCEEDED (HTTP 403) | Delete unused old resources |
| Symptom | How to identify it | Action |
|---|
| Container will not start after upgrade | The main service is not running in docker compose ps | Inspect container logs to identify the cause; roll back using pre-upgrade backups, as described in Version upgrades and migration |
| API returns 500 after upgrade | INTERNAL_ERROR, while it worked before the upgrade | Check for missed manual steps in the relevant version range in Version upgrades and migration |
| Cannot log in after upgrade | API returns 401, or the version on the “About” page has not changed | Confirm frontend and backend image versions match and the containers were recreated |
| Incorrect data after rollback | Rollback used the post-upgrade database | Restore the database backup as part of rollback; see Version upgrades and migration |
- Find specific feature issues by symptom: Frequently asked questions
- Look up HTTP statuses for error codes: Error codes
- Private deployment containers and parameters: Private deployment (Docker)
- Backups, upgrades, and rollback: Version upgrades and migration
