---
title: MCP errors and write recovery
description: Structured failures, CAS, receipts, retries and mount-specific recovery.
url: https://docs.thegram.one/ko/reference/mcp-errors/
lang: en
requested_lang: ko
fallback_from: https://docs.thegram.one/reference/mcp-errors/
tier: current
status:
  component: Thegram Cloud MCP
  deployment: Cloud service https://vault.thegram.one/mcp
  applies_to_version: Latest
  status: GA
  last_verified: "2026-10-25"
  owner: thegram-one/thegram-vault
  public_evidence:
    - https://thegram.one/llms.txt
    - https://github.com/thegram-one/thegram-plugin
  rationale: Current public instructions identify the Cloud MCP service; the page’s desktop socket recovery material is explicitly historical rather than current Cloud onboarding.
source: https://docs.thegram.one/sources/mcp-errors.gram
date_published: "2026-10-12T13:11:21.949Z"
date_modified: "2026-10-16T01:35:51.928Z"
evidence:
  Canonical source SHA-256: 45a707bff1690ed1aa1c1794f5be92831ad5428b82874117afdd19a45f822a86
  Selected revision: r7 · sha256:fffc35266b4f8a9452117465b7f2e77359ff72dbf38a390bc7ec21c9e1710e87
  Local renderer: configured local Thegram renderer · API thegram-web-render/1
  Core source: git+https://github.com/clab-one/thegram-format.git?rev=b16489e1d0d77d38f82d2f61776524737aa31557#b16489e1d0d77d38f82d2f61776524737aa31557
---

# MCP errors and write recovery

<div class="gram-doc-anchor" id="e0-portal-reference-mcp-errors"></div>

This page retains source-pinned Core and legacy desktop error evidence. Desktop socket recovery instructions apply only to that historical producer, not current Cloud onboarding. For current API key connection and authentication errors, use the Coding agent API setup guide and live endpoint tool discovery.

### Response model {#h0-3}

MCP `tools/call` failures return tool-level results with `isError` and structured `error:{code,message,...details}`; these are distinct from JSON-RPC transport/protocol errors. The desktop helper separately returns JSON-RPC `-32000` with `data.code: E_APP_NOT_RUNNING` for an unavailable app or JSON-RPC `-32603` when HTTP has no body. Success commonly includes structured content and text content. There is no official per-tool output JSON Schema: consult each tool's documented source-grounded result contract, and treat optional fields as conditional. The compact response budget is 16,384 bytes.

### Exact operational codes {#h0-5}

| Code | Meaning and action |
| --- | --- |
| `E_ARGUMENT` | Invalid/missing input, unknown key, selector conflict, or invalid cursor/limit. Correct the request; do not retry unchanged invalid input. |
| `E_PATH` | Path is outside an allowed local folder/mount. Use the exact mount key from `gram_projects`; never substitute its display name. |
| `E_READ_ONLY` | Approval or mount is read-only. Reads may continue; a write requires an already-authorized writable scope. |
| `STALE_READ` | Document moved during historical read. Read again at current state. |
| `STALE_CURSOR` | Cursor is bound to another document/revision/section. Get a fresh page/read cursor. |
| `E_CURSOR` | Cursor malformed. Obtain a replacement from the corresponding listing/read. |
| `E_REQUEST_REUSE` | The same ID is bound to a different intent. Do not retry the changed request under that ID; retry the original exact intent only to replay it, or use a new ID for a new intent. |
| `COMMIT_UNKNOWN` | Replacement was published but durability is uncertain. Retry only the identical patch with the same request ID; inspect persisted state before claiming success. |
| `STORAGE_CONFLICT` | Cloud provider state conflicted. Re-read persisted state before composing a new write. |
| `PROVIDER_AUTH_REQUIRED` | Provider authorization is needed. No successful remote write is implied. |
| `E_STORAGE` | Storage commit failed. Inspect receipt and sync status, then re-read before retrying. |
| `E_INTEGRITY` | History sequence/hash audit failed. Core rejects writes to corrupt history; do not repair by editing the trailer. |
| `E_MIGRATION` | Legacy data cannot be converted by the requested path. Preserve source and use the supported migration contract. |

Other source-defined errors include `E_CORE_UNAVAILABLE`, `E_TIMEOUT`, `E_CORE`, `E_INTERNAL`, `E_UNKNOWN_TOOL`, `E_CONTEXT_BUDGET`, `E_TOO_MANY_DOCUMENTS`, `E_TIME_NOT_RECORDED` and `E_REQUEST_ID`. Read the returned code/details; codes are not interchangeable.

### Safe CAS sequence {#h0-8}

1. Read current document identity `{path,rev,hash}`.
2. Prepare one intended patch with that revision/hash, a unique 1–128-character request ID, and nonempty operations.
3. The public tools expose no receipt tool. For an uncertain `gram_patch`, resend the exact same request_id and unchanged path, base_revision, expected_hash, and operations; Core replays the original receipt.
4. If Core reports stale/CAS conflict, reread and rebase the human intent on the new content; send a new request ID.
5. On mounted cloud writes, verify returned `sync.state: synced`; successful MCP completion alone is not the remote persistence check.

A request_id binds canonical intent, including document ID, operation, base_revision, expected_hash, operations, effective_at, and context. An A-to-B-to-A reversal has a different CAS base and is a different intent, so reusing the first ID returns E_REQUEST_REUSE.

### Create and retry boundaries {#h0-11}

`gram_create` has no request_id. If its response is uncertain, read the target path before further action. Creating at an existing path returns `STALE_REVISION` with `Create target already exists`; do not treat it as a patch or overwrite.

Only retry `gram_patch` by resending the exact same request_id and complete intent. The public MCP API has no standalone receipt tool. The shortened displayed hash maps to a full artifact hash held by the caller's gateway; if a short hash is no longer resolvable, reread rather than guessing.

### Local/cloud boundary {#h0-14}

Local document tools require the app's approved vault scope; profile and capabilities are available without document approval. Read-only approvals reject create/patch. Cloud tools open a caller-scoped workspace, use exact mount paths, and commit back to the provider. Cloud capability reports semantic search unavailable and `auto` uses lexical fallback; local semantic behavior is runtime-probed. Local mount sync may be pending; cloud successful writes report synced. No tool bypasses the caller's existing authority.

### Exact source-backed error messages {#h0-16}

| Surface | Code | Actual message | Sources |
| --- | --- | --- | --- |
| MCP tool result | `E_ARGUMENT` | `Unknown argument ` | thegram-vault/internal/mcp/gateway.go#335359731a3724bb0bf7a02093e3d7e1bbd93ccda3bbdff143b6178eec98a436 |
| MCP tool result | `E_CURSOR` | `Invalid list cursor` | thegram-vault/internal/mcp/tools_common.go#f243590ff0ab46a241c752ae104c538e5064c869525209dfc7219572d6d5523c |
| MCP tool result | `E_CURSOR` | `Invalid section cursor` | thegram-vault/internal/mcp/memory.go#cf97b451501c97d5db3c43836171a65ce221b9105d1b3c75ae58ccefc93e72e1 |
| MCP tool result | `E_CURSOR` | `Invalid changes cursor` | thegram-vault/internal/mcp/memory.go#cf97b451501c97d5db3c43836171a65ce221b9105d1b3c75ae58ccefc93e72e1 |
| MCP tool result | `E_CURSOR` | `Invalid context cursor` | thegram-vault/internal/mcp/tools_entity.go#04d41ed2634d5904fa812be53c92c70a06403d78334890b9791c168b8f89c9f0 |
| MCP tool result | `E_CURSOR` | `Invalid state cursor` | thegram-vault/internal/mcp/tools_history.go#c2d2b98e94a1cebbc9aadae0e931500c109b61fe44e90ad2f9e1bc6b76e499c8 |
| desktop JSON-RPC -32000 | `E_APP_NOT_RUNNING` | `Thegram is not running. Open the Thegram app, then retry.` | thegram-desktop/Helper/ThegramMCP.swift#87b7fdb6a576da59e84d86ae32624e452f5da7e3c4138b6f539374437556e6dd |
| desktop JSON-RPC | `JSON-RPC -32603` | `Thegram answered HTTP \(response.status) with no body` | thegram-desktop/Helper/ThegramMCP.swift#87b7fdb6a576da59e84d86ae32624e452f5da7e3c4138b6f539374437556e6dd |
| MCP tool result | `STALE_READ` | `The document changed while it was read; read again` | thegram-vault/internal/mcp/tools_common.go#f243590ff0ab46a241c752ae104c538e5064c869525209dfc7219572d6d5523c |
| MCP tool result | `STALE_READ` | `The document was replaced while it was read` | thegram-vault/internal/mcp/tools_history.go#c2d2b98e94a1cebbc9aadae0e931500c109b61fe44e90ad2f9e1bc6b76e499c8 |
| MCP tool result | `STALE_CURSOR` | `The documents changed since this cursor; list again` | thegram-vault/internal/mcp/tools_common.go#f243590ff0ab46a241c752ae104c538e5064c869525209dfc7219572d6d5523c |
| MCP tool result | `STALE_CURSOR` | `The documents changed since this cursor; ask again without cursor` | thegram-vault/internal/mcp/memory.go#cf97b451501c97d5db3c43836171a65ce221b9105d1b3c75ae58ccefc93e72e1 |
| MCP tool result | `STALE_CURSOR` | `Cursor belongs to another document or revision` | thegram-vault/internal/mcp/tools_history.go#c2d2b98e94a1cebbc9aadae0e931500c109b61fe44e90ad2f9e1bc6b76e499c8 |
| MCP tool result | `STALE_CURSOR` | `The cursor belongs to another document, revision or section` | thegram-vault/internal/mcp/memory.go#cf97b451501c97d5db3c43836171a65ce221b9105d1b3c75ae58ccefc93e72e1 |
| MCP tool result | `E_REQUEST_REUSE` | `request_id belongs to another intent` | thegram-format/native/api.rs#a7e13ec4b422ae4907c7d7eac481267103f9b4b86248e706a82251cc597a5e02 |
| MCP tool result | `E_REQUEST_ID` | `Nonempty request_id required` | thegram-format/native/api.rs#a7e13ec4b422ae4907c7d7eac481267103f9b4b86248e706a82251cc597a5e02 |
| MCP tool result | `E_CAS_REQUIRED` | `base_revision required` | thegram-format/native/api.rs#a7e13ec4b422ae4907c7d7eac481267103f9b4b86248e706a82251cc597a5e02 |
| MCP tool result | `E_CAS_REQUIRED` | `Create requires explicit null base_revision` | thegram-format/native/api.rs#a7e13ec4b422ae4907c7d7eac481267103f9b4b86248e706a82251cc597a5e02 |
| MCP tool result | `STALE_REVISION` | `Accepted revision or hash changed` | thegram-format/native/temporal.rs#a143cc67c4518c4599f96af9565ae765c1dcdc770d694b13a8fdc08a03c69c0e |
| Core import-source CAS | `STALE_REVISION` | `Accepted revision or hash changed; preserve both originals` | thegram-format/native/temporal.rs#a143cc67c4518c4599f96af9565ae765c1dcdc770d694b13a8fdc08a03c69c0e |
| MCP tool result | `STALE_REVISION` | `Artifact changed during transaction` | thegram-format/native/store.rs#3bd54253eeee764c2cdf1d3dc1e9c0f4f1d9f96fbd75c66171d96b19a342addc |
| MCP tool result | `STALE_REVISION` | `Create target already exists` | thegram-format/native/store.rs#3bd54253eeee764c2cdf1d3dc1e9c0f4f1d9f96fbd75c66171d96b19a342addc |
| MCP tool result | `COMMIT_UNKNOWN` | `Replacement published but durability is uncertain: {e}` | thegram-format/native/store.rs#3bd54253eeee764c2cdf1d3dc1e9c0f4f1d9f96fbd75c66171d96b19a342addc |
| MCP tool result | `COMMIT_UNKNOWN` | `Marker observed but durability not confirmed: {e}` | thegram-format/native/store.rs#3bd54253eeee764c2cdf1d3dc1e9c0f4f1d9f96fbd75c66171d96b19a342addc |
| MCP tool result | `STORAGE_CONFLICT` | `remote file changed since it was read` | thegram-vault/internal/mcp/workspace.go#3f383dbf85678f084aa1b5c039c72b75188c966c963d6ca534b24450fd2cc826 |
| MCP tool result | `STORAGE_CONFLICT` | `remote file changed and local restoration failed` | thegram-vault/internal/mcp/workspace.go#3f383dbf85678f084aa1b5c039c72b75188c966c963d6ca534b24450fd2cc826 |
| MCP tool result | `E_STORAGE` | `workspace storage is not configured` | thegram-vault/internal/mcp/workspace.go#3f383dbf85678f084aa1b5c039c72b75188c966c963d6ca534b24450fd2cc826 |
| MCP tool result | `PROVIDER_AUTH_REQUIRED` | `Google Drive must be reconnected` | thegram-vault/internal/mcp/workspace.go#3f383dbf85678f084aa1b5c039c72b75188c966c963d6ca534b24450fd2cc826 |
| MCP tool result | `E_PATH` | `Absolute paths are outside the approved folder` | thegram-vault/internal/mcp/paths.go#754797578ba9858e6db8707f17ca9ceed82914215e83e00e437a05e925bff936 |
| MCP tool result | `E_PATH` | `Path does not start with a mounted collection` | thegram-vault/internal/mcp/paths.go#754797578ba9858e6db8707f17ca9ceed82914215e83e00e437a05e925bff936 |
| MCP tool result | `E_PATH` | `Path is outside the approved folders` | thegram-vault/internal/mcp/paths.go#754797578ba9858e6db8707f17ca9ceed82914215e83e00e437a05e925bff936 |
| MCP tool result | `E_PATH` | `Path is outside an approved folder or hidden` | thegram-vault/internal/mcp/paths.go#754797578ba9858e6db8707f17ca9ceed82914215e83e00e437a05e925bff936 |
| MCP tool result | `E_PATH` | `Vault mounts support writes only to top-level documents` | thegram-vault/internal/mcp/paths.go#754797578ba9858e6db8707f17ca9ceed82914215e83e00e437a05e925bff936 |
| MCP tool result | `E_READ_ONLY` | `This mounted folder is read-only to agents` | thegram-vault/internal/mcp/paths.go#754797578ba9858e6db8707f17ca9ceed82914215e83e00e437a05e925bff936 |

## Source

<div class="gram-record" id="e0-format-language" data-record-type="source">

**Source:** .gram language specification

Reference: [https://github.com/clab-one/thegram-format/blob/main/spec/language.md](https://github.com/clab-one/thegram-format/blob/main/spec/language.md)

</div>

<div class="gram-record" id="e0-format-rich" data-record-type="source">

**Source:** Current rich document specification

Reference: [https://github.com/clab-one/thegram-format/blob/main/spec/rich-document.md](https://github.com/clab-one/thegram-format/blob/main/spec/rich-document.md)

</div>

<div class="gram-record" id="e0-format-history6" data-record-type="source">

**Source:** Current History/6 specification

Reference: [https://github.com/clab-one/thegram-format/blob/main/spec/source-history-render.md](https://github.com/clab-one/thegram-format/blob/main/spec/source-history-render.md)

</div>