# Troubleshooting Troubleshoot service startup, page access, and data connections. 排障 · 模块: reference · 使用者 · 部署形态：资料未说明 · 已确认产品版本：资料未说明 · 来源：现有文档 Use this page to troubleshoot system issues such as service startup, page access, and data connections. See [Frequently asked questions](https://docs.asktable.com/en/reference/faq) for issues using individual features. ## Before you begin 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. ## Key constraints | 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"}` | — | ## Troubleshooting ### Services and pages | 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)](https://docs.asktable.com/en/deploy/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](https://docs.asktable.com/en/admin/license) | | 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 | ### Cannot connect data | 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 | ### Conversations and queries | 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](https://docs.asktable.com/en/admin/models) | ### Permissions and access | 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](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 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 | ### Models and web search | 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](https://docs.asktable.com/en/admin/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” | ### Feishu, embedding, 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); private deployment must also add the search service container first, as described in [Deploy AI Search](https://docs.asktable.com/en/deploy/ai-search) | | Scheduled report was not delivered | `REPORT_FAILED` (HTTP 400) | Create the report again; see [Scheduled analysis reports](https://docs.asktable.com/en/integrations/scheduled-reports) | | API returns 403 with a quota message | `RESOURCE_QUOTA_EXCEEDED` (HTTP 403) | Delete unused old resources | ### Upgrades and rollback | 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](https://docs.asktable.com/en/deploy/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](https://docs.asktable.com/en/deploy/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](https://docs.asktable.com/en/deploy/migration) | ## Next steps - Find specific feature issues by symptom: [Frequently asked questions](https://docs.asktable.com/en/reference/faq) - Look up HTTP statuses for error codes: [Error codes](https://docs.asktable.com/en/reference/error-codes) - Private deployment containers and parameters: [Private deployment (Docker)](https://docs.asktable.com/en/deploy/docker) - Backups, upgrades, and rollback: [Version upgrades and migration](https://docs.asktable.com/en/deploy/migration)