# Troubleshooting and FAQ (P0 Scenarios)

Use this guide to diagnose the most common issues across the MOI console, AI Studio, Genesis, and MatrixOne instances. For exact HTTP status codes and JSON error codes, consult the [Error Codes and Status Reference](../reference/error-codes.md).

## 1. Sign-in, invitations, and workspace permissions

| Symptom | Likely cause | What to check |
| --- | --- | --- |
| Missing buttons such as **Create Workflow**, **Create Knowledge Base**, or user management | Your role in the current workspace lacks that global or object permission | Ask a workspace administrator to check your role assignments under [Role permissions](../guides/ai-studio/permissions/roles.md) |
| Account invitations blocked after 10 users | Account-level registration invitations (default cap 10 per user) are separate from inviting existing users into a workspace | To collaborate inside a workspace with existing MOI users, invite them in [User management](../guides/ai-studio/permissions/users.md); see [Account management](../guides/billing/account.md) |
| Credential creation or model calls prompt for identity verification | Your deployment enforces real-name verification | Verify using your currently verified phone number and real name; see [Complete real-name verification](../guides/billing/real-name.md) |
| Operations on another workspace return `404` / `ErrNotFound` | Wrong workspace active in the top bar or mismatched `X-Workspace-ID` header | Copy the exact target ID from the [Workspace](../guides/ai-studio/resource-center/workspace.md) switcher and retry |

## 2. API authentication and credential errors

| Symptom | Likely cause | What to do |
| --- | --- | --- |
| AI Studio request fails with `ErrMultipleAuthCredentials` | Multiple credentials sent together—commonly browser login cookies stored automatically by Postman, `requests.Session`, or browser fetches | Send only `X-API-Key` (and `X-Workspace-ID` when required), and disable or clear cookies for API-key clients; see [Troubleshoot failed calls](../developer/quickstart/ai-studio/http-api.md#troubleshoot-failed-calls) |
| Sending `Authorization: Bearer` to AI Studio returns `401` / expired session | Mixing Genesis and AI Studio header conventions | Use `Authorization: Bearer` for Genesis, and `X-API-Key` for AI Studio |
| Genesis request returns `402 insufficient_credit` | Account Credit balance is insufficient | Recharge via [Top Up Credit](../guides/billing/manage-billing.md) and confirm the balance updates before retrying |
| Model calls or published dynamic services return `429` | API Key / service-account RPM/TPM/concurrency limit or upstream provider throttling | Inspect the `Retry-After` header and retry with exponential backoff, or check allowed models in [List models](../reference/api/genesis/models.md) |

## 3. Data ingestion, connectors, and knowledge bases

- **REST API or storage connector verification fails**: Confirm authentication type, credential validity, reachable URL/endpoint, and pagination behavior in [Connect a REST API](../guides/ai-studio/data-sources/rest-api.md).
- **Load task stalls or fails**: Expand task run details under [Load tasks](../guides/ai-studio/data-sources/load-tasks.md) to verify source encoding, Catalog table schema mapping, and whether the target compute instance is ready.
- **Knowledge base Q&A missing citations or NL2SQL cannot find tables**: Confirm document ingestion/indexing completed cleanly ([Create knowledge bases and configure sources](../guides/ai-studio/knowledge-bases/create-and-sources.md)), and confirm custom SQL tables are properly registered in Catalog ([SQL editor](../guides/ai-studio/processing/sql-editor.md)).

## 4. Compute instances, managed sandboxes, and billing

| Symptom | Likely cause | What to do |
| --- | --- | --- |
| Compute instance fails to activate or start | Pre-activation Credit check failed due to insufficient balance, or custom Python dependency validation failed | Verify Credit balance in [View Costs and Usage](../guides/billing/cost-and-usage.md); for custom Python packages, verify `requirements.txt` syntax and allowed index URLs in [Compute instances](../guides/ai-studio/resource-center/compute.md#configure-custom-python-dependencies) |
| Managed runtime stays in `Waiting` or returns `SANDBOX_QUOTA_EXCEEDED` | Workspace reached its managed sandbox quota or compute pool queue | Delete unused managed environments or ask a platform administrator to raise the workspace sandbox quota |
| Public network call inside managed sandbox is blocked | Either the tool was not enabled or `domain:port` was omitted from the network allowlist | Allow both the **tool** (such as `pip`, `git`, or `curl`) and the target **`domain:port`** in [Terminals, networking, and maintenance](../guides/ai-studio/agents/runtime-environments/manage.md) |
| Continuous compute charges while no chat is running | A **managed runtime environment** remains ready and bound | Managed environments accrue continuous per-minute charges from **Ready** until deleted and stopped (unlike temporary in-chat ephemeral sandboxes); see [How compute instances and sandboxes are billed](../guides/billing/credit-and-pricing.md#how-compute-instances-and-sandboxes-are-billed) |

## 5. IM channels and agent integrations

For Feishu, WeCom, Slack, or Telegram webhook verification failures, signature errors, or missing replies, follow [IM integration troubleshooting](../guides/ai-studio/agents/manage-agents/im-connection/troubleshoot.md).

## 6. MatrixOne database instances and billing ledger boundaries

- **Connection refused or timed out**: Verify the instance is running, confirm endpoint host/port and TLS settings, and add your client egress IP to the instance allowlist ([Database instances](../guides/matrixone/instances.md)).
- **SQL permission errors**: Sign in with explicit `username:role_name` context and confirm `GRANT` privileges ([Permissions: MatrixOne](../guides/matrixone/permissions.md)).
- **Database instance charges not in Credit ledger**: MatrixOne CU, storage, and renewal invoices are tracked in the instance console ledger; see [Instance Billing](../guides/billing/matrixone-billing.md).

## Before opening a support ticket

If the checks above do not resolve the issue, open **Feedback Assistant** in the console or follow [Support and feedback](support.md) with these diagnostics (never share raw passwords, AK/SK, or access tokens):

- Workspace ID, affected resource name, and exact timestamp.
- Relevant load task ID, workflow run ID, conversation ID, SQL `Query ID`, Genesis `Request ID`, or top-up order number.
- Full HTTP status code, JSON error `code`, and redacted screenshots.
