Freshness and staleness errors

cix answers from an index tied to your repository's git state. When the bytes you are editing and the state the server can verify drift apart, tools refuse with one of the codes below instead of acting on stale data. Every refusal is recoverable; none of them means your work is lost.

STALE_OVERLAY_REQUIRED

A write tool (add_symbol, edit_symbol, refactor_rename) needs your uncommitted work uploaded as a working-tree overlay, and the overlay must be anchored to a resolvable git state: a branch name plus a commit id (head_sha). This error fires when that anchoring is missing — typically a detached HEAD, a repo with no tracked remote branch, or a client that could not resolve the current commit.

Recover: return to a resolvable state (check out a branch that tracks a remote, commit if needed), then retry. The client uploads the overlay automatically once branch and head commit resolve. If readers work but writers keep failing this way, reconnect the MCP session — a long-lived session can hold stale git state.

STALE_BYTES

Optimistic concurrency on the write path. The bytes your edit was computed against no longer match the latest uploaded overlay for this file — another writer, or a change made outside cix, landed between your read and your write. The response includes the mismatching hashes. cix never auto-merges across this drift.

Recover: re-read the file (get_lines / get_symbol), recompute the edit against the fresh bytes, retry.

STALE_INDEX

The indexed copy of the file is behind what your request implies. The index has not yet caught up with a recent push or edit.

Recover: call refresh_index (pass the file path for a single-file refresh), then retry the original call.

STALE_ANCHOR

An old_text-anchored edit matched bytes that have since moved or changed — the anchor was computed against a version of the file that is no longer current.

Recover: re-read the target range and re-derive old_text from the current bytes, then retry.

INDEXED_SOURCE_MISMATCH

The symbol you are editing has different source bytes in the live file than in the index — the file changed after it was last indexed, so span-based edits cannot be trusted.

Recover: refresh_index for the file, re-read the symbol, retry. If this repeats right after a branch switch, one refresh of the file heals the overlay for the new branch.

COMMITTED_NOT_PUSHED

A file-content read needed committed bytes, but the commit exists only locally — it has not been pushed, so the server cannot fetch it.

Recover: push the branch, or rely on tools that serve working-tree bytes. This is the one freshness code where the fix is a push, not a refresh.

The pattern

All six codes are the same contract seen from different angles: cix refuses to act on bytes it cannot verify. The refusal always names the smallest recovery step. Prefer that step over rebuilding state from scratch — see [concept-overlay] for how uploads and anchoring work, and [concept-freshness-verdicts] for the freshness fields read responses carry.