MCP errors and write recovery · r6
Archived revision r6, recorded 2026-10-14T02:42:48.365Z by portal-reference-finalize. Current page: MCP errors and write recovery.
Response model
Section titled “Response model”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
Section titled “Exact operational codes”| 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
Section titled “Safe CAS sequence”- Read current document identity
{path,rev,hash}. - Prepare one intended patch with that revision/hash, a unique 1–128-character request ID, and nonempty operations.
- 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. - If Core reports stale/CAS conflict, reread and rebase the human intent on the new content; send a new request ID.
- 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
Section titled “Create and retry boundaries”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
Section titled “Local/cloud boundary”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
Section titled “Exact source-backed error messages”| 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
Section titled “Source”Source: .gram language specification
Reference: https://github.com/clab-one/thegram-format/blob/main/spec/language.md
Source: Current rich document specification
Reference: https://github.com/clab-one/thegram-format/blob/main/spec/rich-document.md
Source: Current History/6 specification
Reference: https://github.com/clab-one/thegram-format/blob/main/spec/source-history-render.md
Source and renderer evidence
- Canonical source SHA-256
45a707bff1690ed1aa1c1794f5be92831ad5428b82874117afdd19a45f822a86- Selected revision
r6 · sha256:2870e1e5d1531e39c3bbab9c2f994ea7e8377cc7192a9a777935a95bf6bf5089- 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
Canonical source: 6.gram