> ## Documentation Index > Fetch the complete documentation index at: https://docs.sidecars.ai/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshooting > Every error the Sidecars MCP server returns, keyed on the text you see, with what causes it and how to recover: connection, sign-in and scopes, workspace, permissions, and write conflicts. ## Can't connect | What you see | Cause | Fix | | ---------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | The first tool call returns `401` | Normal. The challenge is what starts your host's OAuth flow. | Let the host open the sign-in page. If it does not, re-add the server and run its login step ([Connect](/connect)). | | The host expects an SSE stream or a session id | The server is JSON-only and stateless. Current hosts handle this. | Use a current host version, or bridge with `npx -y mcp-remote https://mcp.sidecars.ai/mcp`. | | The host only speaks stdio | Remote HTTP is not supported by that host. | Same `mcp-remote` bridge. | | Opening the URL in a browser shows an error | The URL is for MCP clients, not browsers. | Paste it into a host. | | Batched JSON-RPC requests are rejected | Batching was removed from the protocol. | Send one request per POST. | | Your host lists a docs server from this site | Mintlify hosts a search server for these pages; it cannot act in a workspace. | Use `https://mcp.sidecars.ai/mcp` for the product server. | ## Sign-in and scope errors | What you see | Cause | Fix | | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | `403` with `error="insufficient_scope"` naming a scope | The tool needs a scope the token does not carry. Write, comment, export and document-read tools all arrive by step-up. | Hosts re-run consent for that one scope automatically. If yours does not, reconnect and grant it. | | `401` with `error="invalid_token"` on any method, including `tools/list` | The token is expired, malformed, opaque, or issued for another server. Tokens last 24 hours. | Sign in again from the host. | | Consent asks for `pods:read` or `conversations:write` | Those scopes are advertised but no exposed tool uses them (`conversations:read` is used, by `list_conversations`). | Granting them is harmless; nothing changes. | ## Workspace errors These come back as tool errors after a successful sign-in. Each message names its fix. | Message | Fix | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | | Your account is not registered in this workspace app yet. Sign in to the web app first, then re-authenticate this MCP connection. | Open [sidecars.ai](https://sidecars.ai) once, then reconnect. | | Your token carries no active workspace. Re-authenticate this MCP connection and pick a workspace on the consent screen (Claude Code: /mcp; Codex: codex mcp login). | Reconnect and choose a workspace on consent. | | Your workspace hasn't finished syncing yet. Retry in a moment — no fallback workspace is ever substituted. | Retry shortly. | | You are not a member of the workspace this token claims. | Reconnect and pick a workspace you belong to. | To act in a different workspace, reconnect and choose it on the consent screen. ## Permission refusals Refusals use the app's own wording and never reveal whether an artifact exists. | Message | Cause | Fix | | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- | | `Artifact not found` | Not visible to you, in another workspace, or no such id. Also returned for a conversation or pod you cannot reach. | Check the id with `list_documents`; ask the owner to share. | | `This document is read-only for you` | You are a viewer and tried to write or comment. | Ask for commenter or editor access in the app. | | `You can comment on this document but not edit it` | You are a commenter and tried `edit_document` or `write_page`. | Use `add_comment`, or ask for editor access. | | `This document is archived` | Writes to an archived artifact are refused. | Unarchive it in the app. | | `That conversation is archived or gone, so nothing was created.` | `create_document` or `create_page` into an archived room. | Create in another room, or with a `scope` instead. | | `That artifact is an HTML page, not a document — use write_page.` and similar | Wrong tool for the artifact kind. | Use the tool the message names. Tables cannot be edited over MCP. | There is no share, grant, move, link, restore or delete tool, so none of these can be worked around from an agent. See [Authentication and access](/authentication#document-roles). ## Write conflicts Each of these is a tool result with `isError: true` and an `error` code in `structuredContent`. | `error` | Tool | Meaning | Recovery | | -------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- | | `version_conflict` | `edit_document` (`replace_all`), `write_page` | The artifact moved since your read. `current_version` is included; `write_page` adds `diff_excerpt`. | Re-read, merge your change onto the current content, write again with the new version. | | `excerpt_not_found` | `edit_document` | The quoted `section_excerpt` no longer matches. `candidates[]` lists the nearest passages with `similarity`. | Re-read and quote one exactly. | | `excerpt_ambiguous` | `edit_document` | The excerpt matches more than one place. `locations[]` shows each. | Quote a longer passage that matches once. | | `write_conflict` | `edit_document`, `create_document` (retry) | Another agent holds the document's write lease. | Wait `retry_after_seconds` (up to 30) and retry. | | `not_empty` | `edit_document` (`fill_empty`) | The document already has content. | Read it, then `append` or `replace_section`. | | `selection_gone` | `edit_document` | The targeted section was removed while the write queued. | Re-read and resolve a fresh excerpt. | | `format_unavailable` | `export_document` | The format does not apply to that kind. | Documents: markdown, pdf. Pages: html. Tables: csv, json, markdown. | | `export_disabled` | `export_document` | Server-side export is off for the workspace. | Copy the markdown from `read_document` instead. | | `source_missing` | `export_document` | The artifact is empty. | Fill it first. | | `still_rendering` | `export_document` | A render of the same version is in progress. | Retry shortly. | | `render_failed` | `export_document` | The renderer failed. | Report it to the person. | Successful writes can also report an early stop: `stop_reason: "cap"` (the 60,000-character budget; continue with another call) or `anchor_gone` (the section was removed; do not re-add it). A `script_stripped` warning on a page means its scripts are stored but will not run when viewed. ## How errors come back Three kinds, at three layers: Refusals, conflicts and unavailable exports are tool results, not protocol errors. The text says what to do next; diagnostic structure rides in `structuredContent`: ```json theme={null} { "content": [{ "type": "text", "text": "The document moved from version 12 to 14 since you read it. Re-read it, merge your changes onto the current content, and write again with the new expected_version." }], "structuredContent": { "error": "version_conflict", "expected_version": 12, "current_version": 14 }, "isError": true } ``` Failures from below the tool (an access gate, a backend error) use the form `Tool failed: `, where `` contains the gate's own wording, for example `Artifact not found`. Arguments that violate a tool's JSON schema (wrong type, unknown enum value, missing required field) are rejected before the tool runs, as a JSON-RPC `-32602` error. Checks a tool performs itself (`expected_version` missing on `replace_all`, two selectors passed together) come back as `Tool failed:` followed by the check's message, such as `` `section_excerpt` is required for replace_section ``. | Status | When | Header | | ------ | ----------------------------------------------------------- | ------------------------------------------------------------------------------ | | `401` | No token on `tools/call`, or an invalid token on any method | `WWW-Authenticate: Bearer error="invalid_token", resource_metadata="..."` | | `403` | Token lacks the tool's scope | `WWW-Authenticate: Bearer error="insufficient_scope", scope="documents:write"` | Hosts handle both by starting or re-running the OAuth flow. ## Limits | Limit | Value | | --------------------------------------- | --------------------------------------------------------------------- | | Search results per call | 1 to 25 (default 10) | | Characters per search excerpt | 2,000, then `[…truncated]` | | Characters per search response | 50,000, then a `[…N more results truncated]` line | | Documents per listing | 1 to 50 (default 50); `truncated: true` when more exist | | Pods enumerated for an org-wide listing | 50, then `truncated: true` | | Read window | 24,000 characters per `read_document` call; page with `offset` | | Content per edit or create | 60,000 characters; longer writes stop early with `stop_reason: "cap"` | | Versions per listing | The 20 most recent | | Idempotency key window | 10 minutes | | Export download URL | 15 minutes | | Busy-document retry hint | Up to 30 seconds | | Access token lifetime | 24 hours | ## Something else Every call is recorded in the workspace's agent activity history, and every write lands as you via the host, so a person can see in the app which client did what. Writes are checkpointed and undoable there. If a result does not match this page, note the exact text and the tool name when you report it.