# Troubleshooting guide This page indexes known error codes, symptoms, and resolution steps observed across Chat, Studio, Connected Apps, Model Intelligence, the Gateway, approvals, credentials, and model routing. ## Gateway errors | Code | Meaning | Resolution | |---|---|---| | `INVALID_REQUEST` | The request body failed basic validation (e.g. missing `messages` array). | Check the request format against the [chat completions API](/docs/gateway/overview). | | `MESSAGES_REQUIRED` | The chat completions endpoint requires at least one message in the `messages` array. | Add a `messages` array with at least one entry. | | `SETUP_REQUIRED` | An AI provider is not configured for the requested route. | Configure a provider API key via the Gateway dashboard or BYOK. | | `PROVIDER_UNAVAILABLE` | The upstream AI provider could not complete the request. | The request was forwarded to fallback providers if configured. If no fallback succeeded, check provider health in the Gateway dashboard. | | `PROVIDER_NOT_IMPLEMENTED` | The selected provider is known but not yet wired for live execution. | Choose a different provider or route. | | `INTERNAL_ERROR` | Unexpected server error. | Retry the request. If it persists, check Gateway server logs. | ## Authentication and API key errors | Code | Meaning | Resolution | |---|---|---| | `missing_api_key` | The request did not include an API key in the `Authorization` header. | Add `Authorization: Bearer ` to the request headers. | | `invalid_api_key` | The provided API key is not recognised. | Verify the key was created and has not been revoked. Keys are hashed with SHA-256 + salt and cannot be recovered. | | `revoked_api_key` | The API key has been revoked and is no longer valid. | Create a new API key in the Gateway dashboard. | | `expired_api_key` | The API key has passed its expiration date. | Create a new API key or update the expiration. | | `insufficient_scope` | The key lacks the required scope for the requested operation. | Ensure the key has the `gateway:invoke` scope for chat completions. | ## Provider credential errors | Symptom | Likely cause | Check | |---|---|---| | Gateway returns `SETUP_REQUIRED` for a provider | Provider API key is not configured (no environment variable and no BYOK credential) | Set the provider's environment variable or store a BYOK credential. | | `test_failed` credential status | The stored credential failed a connectivity test | Verify the key is valid in the provider's dashboard. | | Desktop shows "Credential not available" | Electron `safeStorage` is unavailable | Use environment variables as fallback. | ## Approval errors | Symptom | Likely cause | Check | |---|---|---| | Approval request shows `stale` status | The payload hash no longer matches the current state | Re-submit the approval request with updated content. | | Approval request shows `blocked` status | Policy prohibits the action at the configured risk level | Review the approval policy configuration. | | Approval request expired before a decision | The `expiresAt` timeout was reached | Create a new request with a longer expiry window. | ## Model routing errors | Symptom | Likely cause | Check | |---|---|---| | Requested model not available | The model is not in the Gateway model catalog or is restricted by provider allowlist | Check the [model catalog](/docs/models/overview). | | Provider skipped in routing | Circuit breaker open, provider not configured, or blocked by allowlist | Check provider health in the Gateway dashboard. | | Request fails with no fallback | All eligible providers are unavailable | Verify at least one provider is configured and has a closed circuit breaker. | ## Chat | Symptom | Likely cause | Check | |---|---|---| | Stream stalls or errors mid-answer | Transient provider or network failure | Cancel and retry once; if it persists, check [status](/docs/resources/status-and-support). | | Signed-out loop / session errors | Expired or invalid session | Sign out and back in; clear site cookies for `chat.upcube.ai` if it repeats. | | Voice session answers `VOICE_NOT_CONFIGURED` | Voice not configured on this deployment | Nothing to fix client-side; the deployment names the missing server key. | | Model behaves unexpectedly | Capabilities differ per model | Confirm the model selector choice; compare capabilities on [Model Intelligence](/model-intelligence). | ## Studio | Symptom | Likely cause | Check | |---|---|---| | Workbench unreachable after sign-in | Private-alpha enrollment missing | Access requires enrollment; see [status](/docs/resources/status-and-support). | | Job fails with `VALIDATION_ERROR` | Bad prompt, unknown task, or bad parameters | Fix the named field; nothing was reserved or spent. | | Job lands in an uncertain outcome | Provider state could not be confirmed | Read the job's recovery steps; check activity before retrying. | | Empty catalog or missing endpoints | Catalog fetch failure | This is an error, never an empty result — retry; persistent emptiness is a bug, report it. | ## Connected Apps and Flow | Code | Meaning | Resolution | |---|---|---| | `NEEDS_REAUTH` | Provider grant expired or revoked upstream | Reconnect the connection from settings. | | `MISSING_SCOPE` / `SCOPE_NOT_GRANTED` | Action needs an ungranted scope | Grant the named scope or decline the action. | | `APPROVAL_REQUIRED` | Action needs your approval | Approve the exact action, or deny it. | | `APPROVAL_MISMATCH` / `APPROVAL_EXPIRED` | Approval no longer matches or timed out | Review and approve again. | | `ADMIN_POLICY_BLOCKED` | Workspace admin blocked the action | Ask your admin for access. | | `CONNECTION_NOT_FOUND` | Connection revoked or never existed | Reconnect; pending actions on it will not run. | | `UNKNOWN_OUTCOME` | Completion could not be confirmed | Check activity before retrying. | ## Model Intelligence API | Symptom | Likely cause | Check | |---|---|---| | `/api/mi/v1/models/:slug` answers 404 | Unknown slug | List the index and copy the slug exactly; slugs are case-sensitive. | | 301 redirect | Slug moved | Follow the redirect to the canonical slug. | | 410 `removed` | Model deliberately removed | It will not come back under this slug; pick another model. | | 500 `quarantined` | Model held for review | Read the `reason`; retry later. | ## See also - [FAQ](/docs/resources/faq) - [Status and support](/docs/resources/status-and-support) - [Chat overview](/docs/chat/overview) - [Studio overview](/docs/studio/overview) - [Managing connections](/docs/connected-apps/managing-connections)