ThegramDocs

Reference

MCP errors and write recovery

Structured failures, CAS, receipts, retries and mount-specific recovery.

Download r3 source
Explore as .gram

Download exact selected revision source

Source
r3 · Now
Document

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.

Exact gateway/Core error messages

Code

Actual message

Source

STALE_READ

The document changed while it was read; read again

thegram-vault/internal/mcp/tools_common.go

STALE_READ

The document was replaced while it was read

thegram-vault/internal/mcp/tools_history.go

STALE_CURSOR

The documents changed since this cursor; list again

thegram-vault/internal/mcp/tools_common.go

STALE_CURSOR

The documents changed since this cursor; ask again without cursor

thegram-vault/internal/mcp/memory.go

STALE_CURSOR

Cursor belongs to another document or revision

thegram-vault/internal/mcp/tools_history.go

STALE_CURSOR

The cursor belongs to another document, revision or section

thegram-vault/internal/mcp/memory.go

E_REQUEST_REUSE

request_id belongs to another intent

thegram-format/native/api.rs

STALE_REVISION

Accepted revision or hash changed

thegram-format/native/temporal.rs

STALE_REVISION

Accepted revision or hash changed; preserve both originals

thegram-format/native/temporal.rs

STALE_REVISION

Artifact changed during transaction

thegram-format/native/store.rs

COMMIT_UNKNOWN

Replacement published but durability is uncertain: {underlying error}

thegram-format/native/store.rs

COMMIT_UNKNOWN

Marker observed but durability not confirmed: {underlying error}

thegram-format/native/store.rs

STORAGE_CONFLICT

remote file changed since it was read

thegram-vault/internal/mcp/workspace.go

STORAGE_CONFLICT

remote file changed and local restoration failed

thegram-vault/internal/mcp/workspace.go

E_STORAGE

workspace storage is not configured

thegram-vault/internal/mcp/workspace.go

PROVIDER_AUTH_REQUIRED

Google Drive must be reconnected

thegram-vault/internal/mcp/workspace.go

E_READ_ONLY

This mounted folder is read-only to agents

thegram-vault/internal/mcp/paths.go

Source

r3 · Now

r3 · · Portal-reference-finalize

Structured failures, CAS, receipts, retries and mount-specific recovery.

0Needs attention

Source3

.gram language specification
Current rich document specification
Current History/6 specification