Reference
MCP errors and write recovery
Structured failures, CAS, receipts, retries and mount-specific recovery.
Explore as .gram
Text
# MCP errors and write recovery
## Response model
Tool failures are returned as MCP tool results with `isError` and structured `error:{code,message,...details}`; they are not JSON-RPC transport errors. 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
| 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` | Same request ID now refers to another intent. Do not change and retry under that ID; resolve the original receipt and use a new ID for a new intent. |
| `COMMIT_UNKNOWN` | Receipt could not establish a commit after an uncertain failure. Retry only the identical patch with the same request ID or check receipt/state; do not claim 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
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. If outcome is uncertain, check the receipt; otherwise resend exactly the same intent and request ID.
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.
Never reuse an ID for changed operations. 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
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.
Source
.gram language specification
https://github.com/clab-one/thegram-format/blob/main/spec/language.mdCurrent History/6 specification
https://github.com/clab-one/thegram-format/blob/main/spec/source-history-render.mdr1 · · Portal-reference-contracts
Structured failures, CAS, receipts, retries and mount-specific recovery.
0Needs attention
Source2
.gram language specification
Current History/6 specification
r1 source4188 bytes ·
sha256:6915c94fad4acb73e6a3d5f9841e78cce7e4de56a95434e57b683cbae921c94d@gram 2
doc portal-reference-mcp-errors
t MCP errors and write recovery
d Structured failures, CAS, receipts, retries and mount-specific recovery.
::body
# MCP errors and write recovery
## Response model
Tool failures are returned as MCP tool results with `isError` and structured `error:{code,message,...details}`; they are not JSON-RPC transport errors. 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
| 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` | Same request ID now refers to another intent. Do not change and retry under that ID; resolve the original receipt and use a new ID for a new intent. |
| `COMMIT_UNKNOWN` | Receipt could not establish a commit after an uncertain failure. Retry only the identical patch with the same request ID or check receipt/state; do not claim 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
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. If outcome is uncertain, check the receipt; otherwise resend exactly the same intent and request ID.
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.
Never reuse an ID for changed operations. 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
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.
::end
SRC format-language
t .gram language specification
ref https://github.com/clab-one/thegram-format/blob/main/spec/language.md
SRC format-history6
t Current History/6 specification
ref https://github.com/clab-one/thegram-format/blob/main/spec/source-history-render.md