Every gbrain error carries a stable code. Read code first and fall back to error
(older servers send only error); then follow fix.next as described in
AGENT_OPERATOR_v1. Exit codes are in exit codes.
Offline, gbrain errors <code> prints the same row and gbrain errors --changed the legacy pairs.
Say to your agent:"gbrain returned an error code I don't recognize. Look it up and tell me what to do."
Legacy error values
Under contract v1 an error value never changes. Where a surface sends a legacy value in
error, it also sends the canonical value in code:
error (frozen)
code (canonical)
Meaning
invalid_params
change_reason_rejected
The write's reason was refused before anything was admitted: it is longer than 500 characters, or it looks like it holds a secret.
invalid_params
fact_withdrawn
remember, or an owner gbrain trust release that writes a held fact into its entity page's ## Facts table (a managed brain), refused a claim that was explicitly forgotten for this subject (wire invalid_params, message prefix fact_withdrawn:); nothing was saved, and a refused release leaves the fact held.
permission_denied
insufficient_scope
The connection lacks the OAuth scope the operation requires.
invalid_params
invalid_fence
A facts or takes fence in the page cannot be imported without dropping or guessing rows, so the page (or the file) was not written.
invalid_params
link_cursor_invalid
A get_links / get_backlinks cursor was not one this listing returned: it belongs to another slug, direction, source scope or filter set, or is not a cursor.
invalid_params
not_found
The requested resource does not exist or is not visible to this caller.
page_identity_changed
page_not_found
No page with that slug exists in the selected source.
invalid_params
page_too_large_for_inline
The whole page does not fit one result on this connection, so get_page did not return its body.
invalid_params
result_too_large
The tool's result is larger than this connection can carry in one response, so it was replaced by this error; nothing was cut.
invalid_params
revision_changed
The page changed since the cursor or chunk id was issued, so that position no longer names the same text.
permission_denied
trusted_local_only
The operation runs only from the trusted local CLI on the brain host; no MCP connection can call it.
unknown_operation
unknown_tool
The named tool does not exist or is not callable on this connection.
Codes
absent_from_worktree
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Sync held one file that is committed at HEAD but missing from the working tree (a sparse checkout or a skip-worktree bit, or a local deletion that is not committed); the rest of the source synced.
Sync imports from the working tree, so it cannot import a file that is not on disk, and treating it as deleted would drop a committed file silently. Whether the file comes back or its deletion is committed is the user's choice; classic sync re-screens the hold on every run.
The member a credential (access token, OAuth client or stdio binding) is bound to could not be looked up, so the request was refused and nothing was read or written.
Reading the binding failed with a database error, or with a lock or statement timeout or a dropped connection while the request was submitted. Reading the credential as unbound instead would open every unlabelled page to a labelled-only member, so the request stops, and the same request succeeds once the database answers.
Retry the same request in a few seconds (a write with the same request_id); if it keeps failing, ask the brain operator to run gbrain doctor --json on the brain host. Run: gbrain whoami --json
A labelled-only grant was asked for on the brain owner (gbrain access member labelled-only on), or a labelled-only member was named the owner (gbrain access owner set), so nothing was changed.
The owner reads the whole brain. A labelled-only grant hides every page that does not name its member, so on the owner it would silently hide the owner's own brain from every credential bound to it.
Ask the user which member the group or audience credential should read as; give it its own member and mark that one labelled-only, or clear the grant before naming the owner.
user
repeat the read that failed
3
no
access_labelled_only_unnamed
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A credential whose member is labelled-only tried to create a page that would not name it: the page has no readable_by holding the member or one of its groups, and no folder or page rule over its slug lists them, so nothing was written.
A labelled-only member reads only pages labelled for it, so a page it creates must name it; otherwise it would write a page it could never read back, readable by every other caller its source admits.
Add readable_by naming the member or one of its groups to the frontmatter (readable_by: [alice-example, group:team-a]), or ask the brain operator to add a folder rule over the path that lists it, then submit again with a new request_id.
agent
repeat the read that failed
1
no
access_member_disabled
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The credential (access token, OAuth client or stdio binding) is bound to a member who is disabled, removed or missing, so it was refused at verification and nothing was read.
A credential bound to a member reads as that member. While the member cannot read, the credential is refused rather than silently treated as unbound.
Ask the brain operator to enable the member (gbrain access member enable ) or rebind the credential (gbrain auth rescope --token |--client --member |none).
A member or group id given to an access command, a credential binding or --as is ill-formed or names no usable member, or a declared member email is invalid, taken or ambiguous, so nothing was read or changed.
Ids are matched exactly against page readers; an unknown or disabled member is refused rather than read as unbound, so a typo never previews or binds the wrong view.
Check the id with gbrain access member list --all, or add the member first. Run: gbrain access member list --all --json
A folder-rule edit on a git-backed source with no folder-rule revision yet was refused before anything was written: the first sync after it rebuilds the rules from the committed history of .gbrain/access.yml, and this checkout cannot give that history (a shallow clone, or a partial clone that lacks its Git objects), so that sync would read the whole source as nobody.
A rebuild replays every committed version of the policy file so a narrowing removed by a plain commit stays applied; without the full history it can only fail closed, so the edit refuses up front and the source keeps its current reads.
In the checkout, fetch the full history (git fetch --unshallow) or the missing objects of a partial clone, then run the same gbrain access rule command again. Run: gbrain access rule status --source '{source_id}' --json
user
gbrain doctor --json
1
no
access_policy_invalid
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A source's folder-rule policy (the committed .gbrain/access.yml, or a file given to gbrain access rule import) does not validate, so it was not applied: the last applied rules stay in force and every prefix the bad file names reads as nobody (the whole source when its prefixes cannot be read).
A typo in an access file must never open a folder: an unreadable revision keeps the previous rules and hides what it touches until it is fixed.
Show each problem with its line (gbrain access rule list --source ). Fix the file, commit it with gbrain git commit-push and sync the source (gbrain sync --source --no-pull). Run: gbrain access rule list --source '{source_id}' --json
A narrowing change to a source's folder rules is still being applied to its pages, so the prefixes it touches read as nobody until it finishes; pages under other prefixes keep the last applied rules.
Pages under a newly restricted folder are restamped in batches; until the last batch and its re-check pass land, they read as nobody instead of under the old rules.
Retry shortly. If it stays pending, the apply was interrupted: the brain host finishes it with gbrain access resume --source (database store); a git store finishes with gbrain sync --source --no-pull. Run: gbrain access rule status --source '{source_id}' --json
A source's persisted folder-rule store (sources.config.access_store) disagrees with what this host sees (a git store with no visible work tree, or a database store whose root became a repository), so the persisted store and its applied rules stay in force and nothing switches on its own.
Inferring the store per host would let a missing checkout or a stray git init change which rules apply; only gbrain access rule migrate moves them, and neither direction widens.
On the brain host, preview the move with gbrain access rule migrate --source , then apply it by adding --yes. Run: gbrain access rule status --source '{source_id}' --json
user
gbrain doctor --json
1
no
access_policy_widening_held
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A change to a source's folder rules widens who may read (a rule removed, readers added, the old folder of a moved prefix), so it is recorded but held: the previous rules stay in force until an operator previews it with gbrain access apply --source and approves the printed plan with --yes --expect on the brain host.
Write access to the policy (a git commit or a rule edit) must not be enough to open a folder; widening needs a host-side preview and an explicit approval.
Ask the user whether to approve the widening; the brain host previews it with gbrain access apply --source . Run: gbrain access apply --source '{source_id}' --json
user
repeat the read that failed
1
no
access_rule_invalid
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A folder rule given to gbrain access rule add is invalid (its prefix is not a literal lower-case folder ending in /, holds .. or *, its readers are not member ids or group:, or another rule already covers the prefix), so nothing was written.
Prefixes are matched literally against slugs; a pattern or a typo would silently restrict the wrong pages or none.
Write the prefix as a slug folder ending in / (partners/alice-example/) and the readers as member ids or group:.
The directory the per-member keys would be written to is inside a git work tree, so no key, member or rule was written.
Key files hold live credentials; a file inside a checkout can be committed and pushed.
Point GBRAIN_HOME at a directory outside any git checkout (the default is your home directory) and run the command again.
agent
repeat the read that failed
1
no
access_serves_roster_empty
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
gbrain setup --serves several or gbrain access serves several was given no people (no --members, an empty --members-file), so nothing was written.
Each person gets a member, a folder only they read and a key bound to them; the installer never guesses who they are.
Name every person: --members alice-example,bob-example, or --members-file with one id per line.
agent
repeat the read that failed
1
no
acknowledgment_unavailable
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
This batch is unknown or outside the retained replay window.
A capability this request needs is not configured or not reachable on this brain.
A required capability is not available on this brain. Run gbrain doctor --json to see what is missing.
agent
gbrain doctor --json
1
no
actor_not_attested
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A call named the person it serves (the x-qm-actor header or the acting_user argument) in a way gbrain does not honour: the credential holds no attest right, the operation is not in its attested operations, the argument differs from the header, names anyone but a member-bound credential's own member, or comes without an attested header from a credential bound to no member, or the id is not 1-256 visible ASCII characters; or a write that saves only as an attested person (memory_write) named none; or the request carries x-qm-audience, a channel audience gbrain does not serve yet. Nothing was read or written.
Naming a person decides whose notes are read and written as; only a credential the brain operator granted the attest right may do it, only for the operations it lists, and text in a conversation never chooses it.
Read reason: no_attest_right and op_not_attested are the brain operator's call (gbrain auth rescope --client --attest-actor qm [--attest-ops ]); argument_mismatch, argument_without_attestation, invalid_actor_id, actor_required and audience_not_supported are fixed in the calling harness.
An attested call named a person whose canonical id is not linked to an enabled member of this brain (never linked, unlinked, or the member is disabled or removed), so nothing was read or written.
An attested call reads and writes as exactly one member; an unknown person is refused rather than read as a guest, and unlinking or disabling takes effect on the next call.
The brain operator links the id to its member: gbrain access member link --qm (or enables the member).
sync.admission is not normal, so a managed sync's destructive write (a delete or a keep_db DB-wins reconcile) was not admitted, or was cancelled before it published; nothing was written.
sync.admission (imports_only or classify_only) is the brain-wide switch that pauses what managed sync writes. It is read when the pass pins, inside every admission transaction and again when a destructive write publishes, so a change takes effect at the next group and no destructive write lands after it.
Restore admission with gbrain config set sync.admission normal when the pause is no longer wanted; the next plain sync admits the paused paths again. Run: gbrain sync status --source '{source_id}' --json
agent
gbrain doctor --json
1
no
ambient_capture_off
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
memory.auto_writeback no longer allows this ambient capture lane, so facts extracted from captured session text were dropped before admission.
An explicit off (or an incoherent setting) applies to every capture-lane fact request admitted after the change, including one whose provider call was already in flight; requests admitted earlier still publish.
Correct the request using the message above, then retry.
append_page text held a links fence marker, so nothing was appended.
A page has one links section, and the rows it lists are the page's authored links: an appended links table would replace that section and delete every link it does not list.
Write each link with add_link (from, to, link_type); it adds the row to the page's links section and keeps the rows already there.
agent
repeat the read that failed
1
no
apple_full_disk_access_pending
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
GBrain Helper is running but cannot read Messages because Full Disk Access is off for it, so nothing was imported.
macOS lets an app read the Messages database only after the user switches it on in System Settings; only the user can do that, and a grant can be turned off again later.
Ask the user to open System Settings > Privacy & Security > Full Disk Access and switch on GBrain Helper, then run gbrain sync --source .
Nothing answered on the GBrain Helper's loopback port (the helper is stopped, the Mac is asleep, or apple.helper.port is not set), so nothing was imported.
An imessage source reads only from the helper on the same Mac over 127.0.0.1; it never opens the Messages database itself.
Start GBrain Helper on this Mac and check gbrain config get apple.helper.port names its port, then run gbrain sync --source .
GBrain Helper refused the token gbrain sent, or gbrain has no helper token, so nothing was imported.
The helper answers only a request that carries one of its own tokens with the read:imessage scope; the token is read from the source's --token-env variable when it names one, else GBRAIN_CONNECTOR_IMESSAGE_TOKEN, else the 0600 file ~/.gbrain/connectors/imessage.json.
Save the helper's current token where GBrain reads it, then run gbrain sync --source .
The change needs the owner's explicit approval before it can proceed.
The step needs the user's decision before it runs.
Stop and ask the user; re-run only with the authorization the message names.
user
repeat the read that failed
1
no
archive_audience_unproven
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The conversation archive could not check whether the brain is shared (its client-usage read failed), so it wrote nothing this run.
A brain with no audience declared counts as shared when several clients use it; without that read a page written as personal could be open to other members, so the run publishes nothing.
Rerun gbrain transcripts archive run; if it repeats, declare the audience with gbrain config set brain.audience personal|shared.
The OpenClaw Gateway refused the credential the conversation archive used, so no OpenClaw conversation was read this run; the archive ledger is unchanged.
The Gateway token or device pairing belongs to the user; gbrain never mints or edits one.
Ask the user to give gbrain the Gateway token (GBRAIN_OPENCLAW_GATEWAY_TOKEN, or gateway.auth in the OpenClaw config on this machine), then rerun gbrain transcripts archive run. Run: gbrain transcripts archive status --json
The OpenClaw Gateway answered the conversation archive with an error, so no OpenClaw conversation was read this run; the archive ledger is unchanged.
A temporary condition (a lock, a pending write, a rate limit); the same request can succeed later.
Rerun gbrain transcripts archive run; if it repeats, report the redacted message from gbrain transcripts archive status --json. Run: gbrain transcripts archive status --json
The conversation archive could not reach the OpenClaw Gateway, so no OpenClaw conversation was read this run; the archive ledger is unchanged, so the next run retries safely.
Current OpenClaw keeps live sessions in SQLite owned by its Gateway, and gbrain reads them only through the Gateway's documented RPCs (openclaw gateway call), never the file.
Start the Gateway (openclaw gateway) or point gbrain at it with GBRAIN_OPENCLAW_GATEWAY_URL, then rerun gbrain transcripts archive run. Run: gbrain transcripts archive status --json
On a shared brain the conversation archive held every day and wrote nothing, because no owner member is named and an archive page without readable_by would be open to the whole source.
Only the operator of the brain host can change what blocks this.
Ask the user which enabled member owns the brain, run gbrain access owner set , then rerun the archive; held days are written then. Run: gbrain access owner
Redaction failed for a conversation, so the conversation archive held its days instead of writing them; the next run retries them.
Archive pages are written only after redaction succeeded over the whole session; a day is never written unredacted and never dropped.
Rerun gbrain transcripts archive run; if the day stays held, check the user redaction pattern file named in the held message. Run: gbrain transcripts archive status --json
Another conversation archive run holds this source, so this run read and wrote nothing.
A run decides each day from the archive ledger it read when it started, so two runs at once could publish older history over newer; runs on one source take turns on a database lease.
Wait for the other run to finish, then rerun gbrain transcripts archive run. Run: gbrain status --section locks --json
An atom drain (gbrain dream --drain) stopped with atoms still to extract, or with its backlog count unknown; the batches it finished stay committed and running it again continues.
The drain is bounded by its window, batch cap, per-run budget, job deadline and the cycle lock, and a backlog count that fails is never read as drained; each of these stops can clear on the next run.
Run the printed resume_command again (a budget stop also names the cap it hit). Run: gbrain doctor --only extract_atoms_backlog --json
An atom drain batch extracted nothing and the backlog count did not fall, so the drain stopped instead of spending in a loop; batches it finished earlier stay committed.
What is left is failing, skipped or ineligible, so running the drain unchanged repeats the same empty batch.
Do not rerun this drain unchanged. Run gbrain doctor --json on the brain host and ask the operator to resolve the reported extraction blocker; earlier successful batches remain committed. Run: gbrain doctor --json
host_admin
gbrain doctor --only extract_atoms_backlog --json
1
no
atom_drain_provider_failure
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Every item an atom drain batch attempted failed at the model provider, so the drain stopped; batches it finished earlier stay committed. An item whose atom write did not commit never reached the provider and is not counted here (#7514): its record names the request id and refusal code, and it is held after 3 such failures (held_failed).
An auth, billing, unknown-model or content-block failure repeats on every retry until someone changes the key, plan, model or content, so it is not retryable. A rate limit or a transient failure (5xx, timeout, network, or a cause the provider did not name) can clear by itself, so those reasons stay retryable on exit 11.
For auth, billing or model_not_found, ask the operator to fix the provider key, plan or model named in last_error, then run the drain again; content_block items are skipped once they fail repeatedly. For rate_limit or transient, run the drain again later. Run: gbrain models --json
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
autopilot_no_repo
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
gbrain autopilot --install found no absolute repo directory (sync.repo_path and the default source's local_path are unset or relative), so it installed nothing.
The autopilot daemon syncs a git checkout. A repo-less brain needs no daemon: free upkeep (gbrain maintain --unattended) keeps it maintained.
Pass --repo for a brain kept in git, or check free upkeep with gbrain maintain --status.
agent
repeat the read that failed
1
no
autopilot_pglite_daemon
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
gbrain autopilot --install refused on a PGLite brain: a daemon would hold the single-writer lock all day and block every other gbrain process.
PGLite has one writer. gbrain serve owns the lock and runs the resident sweep; free upkeep runs through gbrain maintain --unattended.
Run gbrain serve. Check upkeep with gbrain maintain --status. For a dedicated-brain daemon, re-run gbrain autopilot --install --force.
agent
repeat the read that failed
1
no
backup_dump_failed
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
gbrain backup create could not dump the PGLite data dir: an entry PGLite cannot read (a socket, FIFO or symlink that is not a dead gbrain socket) is still inside it.
The backup removes only gbrain's own IPC sockets, and only when nothing listens on them; a live gbrain socket, a foreign socket or FIFO, or a symlink is left in place and named in the message, because the database lock proves no other PGLite owner, not who owns an arbitrary endpoint.
Stop the process that uses each named entry (or move the entry out of the data dir), then rerun the same gbrain backup create command. Do not delete an entry something is still listening on. Run: gbrain doctor --json
gbrain backup create refused before writing anything: the PGLite brain's estimated archive size is over the 8 GiB backup-archive cap.
The archive format holds at most 8 GiB of payload and the dump is materialized in memory; refusing up front avoids a long dump that cannot be published.
Take a quiesced physical copy of the data directory instead (stop writers, copy, open the copy in an isolated GBRAIN_HOME, verify with gbrain doctor --json). Run: gbrain doctor --json
A purge ran in the source after a belief ledger payload was prepared, so the append was refused.
A payload prepared outside its appending transaction records the source's purge epoch; appending it after a purge could write the purged text back into history.
Run the same command again; it prepares the payload from the current, redacted state.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
benchmark_empty
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The benchmark file has no tasks.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
benchmark_exists
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A benchmark already exists at the target path.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
benchmark_judge_llm_no_rubric
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Benchmark judge llm no rubric.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
benchmark_judge_qrels_no_expected
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Benchmark judge qrels no expected.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
benchmark_judge_rule_no_checks
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Benchmark judge rule no checks.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
benchmark_judge_unknown_kind
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Benchmark judge unknown kind.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
benchmark_malformed
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A benchmark row is not valid JSON.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
benchmark_missing_judge
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Benchmark missing judge.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
benchmark_missing_task
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Benchmark missing task.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
benchmark_missing_task_id
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Benchmark missing task id.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
benchmark_not_found
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The benchmark file cannot be read.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
benchmark_rule_check_bad_arg
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Benchmark rule check bad arg.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
benchmark_rule_check_malformed
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Benchmark rule check malformed.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
benchmark_rule_check_unknown_op
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Benchmark rule check unknown op.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
body_staging_expired
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The staged body of a large-page write expired before it was published, so nothing was published.
A segmented write stages its segments first and publishes them in one flip; a staging idle past its deadline is collected by maintenance, and publishing without its segments would leave the page missing text.
Send the same write again; it stages a fresh copy.
agent
repeat the read that failed
1
yes
bootstrap_cleanup_pending
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
gbrain bootstrap harness wired and verified the harness, but cleanup of earlier shared-skills enrollments or carried previous token ids is still pending.
A rotation leaves each old enrollment with that enrollment's own credential and then revokes the credential (leave_brain is principal-owned, so a revoked token can never leave). Each carried id is revoked and cleared on its own; an enrollment whose credential is already revoked is inert and finishes locally as credential_revoked. Until every id is cleared the run must not read as success, so --json lists each id's token state and cleanup state.
Follow the fix in the --json result: when every id can converge it re-runs the same bootstrap command; otherwise relay its user_message (restore the cleanup credential or revoke that token by id, or make the current enrollment ready), then re-run. Never revoke a token whose enrollment has not left unless its cleanup credential is lost.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
bootstrap_pending_review
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The bootstrapped benchmark awaits human review.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
bridge_ownership_conflict
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The private local CLI registration is invalid.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
bucket_not_found
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The configured storage bucket does not exist.
A capability this request needs is not configured or not reachable on this brain.
A required capability is not available on this brain. Run gbrain doctor --json to see what is missing.
agent
gbrain doctor --json
1
no
budget_below_recent_runtime
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The cycle's remaining budget fits fewer reflections than dream patterns needs at the recorded runtime, so the in-cycle run was skipped before any spend.
An in-cycle patterns run is sized from dream.patterns.last_run; a run that cannot finish in the budget would spend tokens and be killed.
Run gbrain dream --phase patterns outside the cycle after the user agrees to the paid run (it is not budget-limited and records its cost), or reset the record with gbrain config unset dream.patterns.last_run.
A Google source's configured calendar returned HTTP 403 or 404 to its account, so its sync imports no events.
Without the typed result an unreadable calendar looks exactly like an empty one. The calendar sweep records it in the source's connector state (the run is not failed); gbrain doctor (google_calendar_readable) reads it with no network call and gbrain google status probes it live.
List the calendars the account can read with gbrain google calendars --account <email>, then point the source at one with gbrain sources set-calendar <source> <calendar-id> and run gbrain sync --source <source>. Run: gbrain google calendars --json
agent
gbrain doctor --only google_calendar_readable --json
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
capacity_paused
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A managed sync passed its capacity preflight, then a cumulative write cap (or the background pause line) refused its next admission, so the drain stopped resumable with its cursor and accepted writes intact; nothing failed.
Another writer used the capacity the preflight counted on. Request ids never free, so only the brain host's reversible config raise resumes an ids pause; receipt bytes also free as receipts compact.
Run the gbrain config set the drain report names on the brain host (gbrain doctor --only persistence_capacity --json prints it), then rerun the same gbrain sync; it resumes at the stored cursor.
A temporary condition (a lock, a pending write, a rate limit); the same request can succeed later.
Wait briefly, then retry the same request (writes: reuse the same request_id).
agent
repeat the read that failed
1
yes
change_reason_rejected
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The write's reason was refused before anything was admitted: it is longer than 500 characters, or it looks like it holds a secret.
A reason is kept in page history and, on a page that reaches Git, in the commit message, which a push makes permanent; it is checked before the write is journaled so no copy of a refused reason is stored anywhere.
Shorten the reason, or remove the secret from it, and send the write again.
The file changed after its repair was previewed, so nothing was written.
A repair writes exactly the bytes the operator approved; it binds approval to the previewed file hash and refuses when the file moved on.
Preview the repair again, review the new proposal, and approve its new hash.
agent
repeat the read that failed
1
no
checkout_not_a_source
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
gbrain git commit-push resolved a checkout from the working directory that is not one of this brain's source checkouts on this host (for example a wrapper that changed into another repository), so nothing was staged.
Committing there would write into an unrelated repository, or fail later with a confusing path refusal.
Correct the request using the message above, then retry.
The approved source plan is missing; do not restart from a different revision.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
checkpoint_validation_timeout
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Validating the managed-sync checkpoint timed out.
A temporary condition (a lock, a pending write, a rate limit); the same request can succeed later.
Wait briefly, then retry the same request (writes: reuse the same request_id).
agent
repeat the read that failed
1
yes
chronicle_skipped
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Automatic event extraction (auto_chronicle) skipped or failed this page; reason says why and fix, when present, is the next step.
A capability this request needs is not configured or not reachable on this brain.
Read the receipt or doctor auto_chronicle check: its why explains the reason and its fix, when present, is the next step (paid fixes need the user's agreement).
Live pages have body text but no chunk rows, so search cannot read their body.
A page written without the chunking step (an enrichment stub, an interrupted write) has nothing for search to match; gbrain embed --stale chunks it first, which makes paid embedding calls.
List them with gbrain pages unsearchable --state chunkless_healable --json, then run gbrain embed --stale --catch-up --yes once embedding spend is approved. Run: gbrain pages unsearchable --state chunkless_healable --json
Another apply of the same whole-class file-drift manifest is running, so this run wrote nothing.
One whole-class apply per manifest at a time keeps its progress record and request ids consistent; a second apply would race the first over the same pages.
Wait for the running apply to finish. If it was stopped, rerun the same apply command once its lock expires (the message names when); it resumes at the next window and applies no page twice.
A whole-class file-drift preview found that the reconcile backups its apply would retain exceed the brain's recovery-bytes limit, so nothing was written.
Every page the apply replaces keeps a private reconcile backup, and those backups are bounded by persistence.limits.brain_recovery_bytes; an apply that ran out of room would stop partway through the class.
Show the user the bytes needed and the limit the message names. Raising persistence.limits.brain_recovery_bytes is their call; otherwise settle a smaller class with --only / --skip. Run: gbrain config get persistence.limits.brain_recovery_bytes
The whole-class file-drift manifest no longer matches the hash passed with --expect or the pins its preview saved, so nothing was written.
The apply replaces exactly the pages the user approved; a manifest that was edited, partly written, removed, or previewed for another selection is not that approval.
Run the fresh preview the message prints, show the user its card, and apply its new hash after they agree.
Schema setup (initSchema, which gbrain init, init --migrate-only and upgrade run, and apply-migrations before its orchestrators) refused because the brain's schema version is newer than this gbrain binary's newest migration; nothing in its schema ran and nothing changed.
initSchema replays the binary's whole schema, CREATE OR REPLACE FUNCTION included, before it runs migrations. An older binary sharing the database with a newer one (another host, a lagging cron running apply-migrations or upgrade) used to reinstall its own superseded function bodies, the writer-fence guards among them, over the newer ones and then apply nothing (#7776). Reads do not run schema setup and keep working on the older binary; doctor schema_function_bodies names bodies an older replay already reverted.
Upgrade gbrain on this host (gbrain upgrade) to the release that migrated the database or newer, then rerun the command. Run: gbrain doctor --only schema_version --json
host_admin
gbrain doctor --json
1
no
client_json_unreadable
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Google connect credential error: client json unreadable.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
No OAuth client with this id is registered on this brain, so nothing was read or changed.
A client id is matched exactly; a revoked, deleted or mistyped id has no grant to read or edit.
List the clients with gbrain auth clients --json and retry with an existing client id. Do not register a replacement client or rotate credentials for a lookup miss. Run: gbrain auth clients --json
agent
gbrain auth clients --json
1
no
client_shape_invalid
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Google connect credential error: client shape invalid.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
A time parameter got a value on the wrong clock: known_as_of (recorded time) needs an instant with a zone, not a calendar date (date_for_instant); get_page as_of (valid time) needs a calendar date, not an instant (instant_for_date).
Recorded time (known_as_of) is when the brain had recorded something; valid time (as_of) is when a fact held in the world, as a date. A bare date is ambiguous as a recorded-time instant, and an instant is not an edition date, so each is refused instead of guessed.
Pass a full instant such as 2026-10-01T12:00:00Z to known_as_of, or use as_of where the tool takes a valid-time date.
The commit or publish was refused: it changes files outside the brain's configured source root (git config gbrain.sourceRoot), often a commit made without gbrain git commit-push.
The step needs the user's decision before it runs.
Stop and ask the user; re-run only with the authorization the message names.
gbrain git commit-push (or the brain's committed commit-push helper) committed the other named paths but git left the listed ones out: a modified file flagged assume-unchanged or skip-worktree, or a file inside a nested Git repository.
git add stages nothing for those and still exits 0 (or, for a named skip-worktree file, refuses every path), so reporting success would leave the write uncommitted with nothing in any log.
Read each skipped path and its reason in the message. Clear an assume-unchanged or skip-worktree flag after the user agrees, one flag per call (git update-index --no-assume-unchanged --
The commit was refused before staging: a named file still has unresolved merge conflicts in the index, so committing it would publish its conflict markers.
Git keeps the two sides of a conflicted file (after a merge, rebase or stash pop that stopped on a conflict) as unmerged index entries until someone resolves it; staging it would record the file with its markers as resolved.
Resolve each file with the user (edit out the markers and keep the changes from both sides that belong in the file, since one side may be a write gbrain made), mark it resolved with git add -- , then rerun the commit.
The commit was refused before staging: files another writer had already staged sit under a named directory, and committing them would publish that writer's work.
The step needs the user's decision before it runs.
Stop and ask the user; re-run only with the authorization the message names.
A managed sync import raced a database-only write to the same page, so the file is held and the page keeps the database version; neither was overwritten.
The page's live revision was written by a committed non-sync request after the import was frozen, so the Git file and the database genuinely diverge; choosing either silently would lose the other.
Preview the reconciliation with gbrain sources reconcile --preview, resolve it with the user, then run gbrain sources retry-held and gbrain sync --source --no-pull.
A required configuration value or directory is missing or invalid.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
confirmation_required
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The command needs the user's authorization before it runs; nothing was changed.
The step needs the user's decision before it runs.
Stop and ask the user; re-run only with the authorization the message names.
user
repeat the read that failed
3
no
conflicting_source_scope
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
--source and --all-sources were both given.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
connection_inherited_read_only
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The database refused a write as read-only (SQLSTATE 25006): the server connection defaults to read-only transactions, so nothing was written.
default_transaction_read_only is on for that server connection: session state another client set on a connection a transaction-mode pooler shares, a role or database default, or a read-only server. gbrain opens its transactions READ WRITE and runs a refused autocommit statement once more inside one, so a session default alone no longer stops it; a read-only server (a hot standby) still refuses.
Ask the database operator to reset the pooler's server connections (PgBouncer: RECONNECT, or server_reset_query = DISCARD ALL with server_reset_query_always = 1), find the client that issues session-level SET through the pooler (read-only audits belong in BEGIN READ ONLY ... COMMIT), and check ALTER ROLE / ALTER DATABASE ... SET default_transaction_read_only; then retry. Run: gbrain doctor --json
The managed sync drain lost its database connection three times in a row without committing a page in between, so it stopped where the cursor stands; nothing is recorded against the source.
A pooler drop (ECONNABORTED, ECONNRESET, ETIMEDOUT, EPIPE) is a transport fault, not a page fault: the drain reconnects and retries at 5, 15 and 45 seconds, and the frozen manifest and cursor stay as they are. Three consecutive drops with no progress mean the database is unreachable from here for now.
Check the database URL and pooler (gbrain doctor --json), then rerun the same gbrain sync; it resumes at the stored cursor without re-freezing the manifest.
The connector credential resolves to a different account than the source is pinned to.
A connector source is pinned to the account it first synced, so a swapped credential can never import another account's mail, calendar or repositories into it. The refused run records the mismatch, and autopilot skips the source (unavailable-path) instead of retrying it every interval (#6803).
Restore the credential for the pinned account and run gbrain sync --source (it clears the skip once the account check passes), or add a new source for the new account and archive this one with gbrain sources archive . gbrain doctor --only connector_account_mismatch lists every affected source. Run: gbrain doctor --only connector_account_mismatch --json
The connector source has no working API key; nothing was imported.
The key is read from the source's --token-env variable when it names one, else GBRAIN_CONNECTOR__TOKEN, else the 0600 credential file. None held a key the provider accepted.
Ask the user for the provider API key and save it on stdin: gbrain connectors auth --token -; then gbrain sync --source .
A connector source records to Git, but its Git checkout is not available; the item was held, not written database-only.
A source whose record mode is git commits each item to its checkout before the database row, so git stays the parent. When the checkout is missing the item waits in the holds and is retried on the next sync; it is never written to the database alone, and the record mode is never re-inferred.
Restore the source checkout (gbrain sources status ), then gbrain sources retry-held .
A paid step is waiting for the user's opt-in, so it was skipped and nothing was spent.
A dream-cycle phase that a database-config schema pack newly declares (extract_atoms, synthesize_concepts) did not run before this release; resolving the pack correctly must not start paid model calls on its own (#6393).
Ask the user; with their agreement run gbrain config set cycle..enabled true (the phase skip names the exact command). Run: gbrain schema active --json
agent
repeat the read that failed
1
no
consent_timeout
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Google connect credential error: consent timeout.
The step needs the user's decision before it runs.
Stop and ask the user; re-run only with the authorization the message names.
Running write claims on this host are stamped by a process that writes no persistence_consumers heartbeat row, so its liveness and mode cannot be read.
Every full consumer on this release renews a heartbeat row every 10 s; a claim owner with no row is a gbrain process from before the heartbeat table (an older serve, jobs worker or sync CLI), which also never defers to the resident consumer, so the host may run two full consumers until it is upgraded.
Upgrade and restart the process whose pid the check names (its kind and gbrain version come from the claim stamp); until then the host runs its consumer beside the resident one. Run: gbrain sources writer status --json
agent
gbrain doctor --only consumers_without_heartbeat --json
A synced file is stored in Git through a filter (git-crypt or another clean/smudge driver), so managed sync holds that file alone.
A filter's committed bytes (git-crypt ciphertext, for one) are not the file's text, and gbrain does not run a repository's filter programs during sync, so the file cannot be imported as it stands. The rest of the source keeps syncing.
Leave the file out with sync.exclude, or commit it without the filter so Git stores its text, then sync again.
A synced Markdown file holds NUL bytes (U+0000), so managed sync holds that file alone.
Page text is stored as UTF-8 without NUL bytes, so the file cannot be imported as it stands; NUL bytes usually mean a UTF-16 save (a Windows "Unicode" file), a binary file named .md or a crash-padded file. The rest of the source keeps syncing.
Save a UTF-16 file as UTF-8, remove the NUL bytes, or remove a binary file (or leave it out with sync.exclude), then commit and sync again.
A gbrain-owned content source's shared-skills content receipt names another root than the source and its owner binding, so doctor sync_freshness cannot exempt it and sync does not apply.
A writer transfer or relocation an older release ran (or a sources set-path still to run after a transfer accept) moved the canonical root but left the receipt (config shared_skills.content.v1..) on the old one. Current accepts and set-paths rebind it in their own transaction.
Preview gbrain repair content-receipt-root --source on the owner host and apply it with the hash it prints, or do what it names first (sources set-path, or a self-transfer). Run: gbrain repair content-receipt-root --source '{source_id}'
The content-sanity gate rejected the content because the operator set content_sanity.junk_disposition to reject.
A junk-pattern or operator-literal hit is refused instead of quarantined under that setting, so the page was not written. The same content refuses on every retry.
Remove the matched junk from the file, or switch content_sanity.junk_disposition back to quarantine (a user decision), then import it again.
agent
repeat the read that failed
1
no
content_repair_needs_human
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The content-repair model could not decide whether a held file and the page its frontmatter slug: names are the same page, so nothing was written and a person decides which keeps the slug.
A frontmatter_slug_conflict hold that the deterministic rules cannot clear (the named page exists and shares a type or a title word with the file) goes to the judgment model; needs_human is its answer when the shown frontmatter, headings, opening lines and cross-mentions do not decide identity. Removing the slug: line on a guess would mint a second page for the same thing, and merging on a guess would fold two different things together, so gbrain records the verdict on the hold as codes and slugs, retries nothing until the file changes, and the rest of the source keeps syncing.
Show the user the paragraph gbrain sources status --json renders for the hold (the path and the two slugs). If the two differ, remove the slug: line of the file; if they are one page, merge the unique sections into the page that keeps the slug and delete the other file; then commit and run gbrain sync --source --no-pull. Run: gbrain sources status '{source_id}' --json
Claude Code continued an answer past its output cap and gbrain could not prove the full text, so the claude-cli call returned no text and no tool calls and finished as length.
Print mode reports only the text after an automatic continuation; parsing or dispatching that tail as a complete answer would act on a fragment. The caller retries or escalates as for any capped answer; the gateway does not resend it to a fallback model.
Wait briefly, then retry the same request (writes: reuse the same request_id). Run: gbrain config set '' ''
The read-only convergence shadow (gbrain sync --dry-run --json's convergence, sync status --detail, doctor managed_sync_convergence) could not read the source's level, so it reports status: unavailable instead of counts.
The shadow only predicts what the level-triggered pass would do; the dry run, status and doctor results around it are unaffected and nothing was written.
Read the receipt's message, then rerun the read-only status; report it with gbrain doctor --json if it repeats. Run: gbrain sync status --source '{source_id}' --detail --json
A conversion review list, decisions file or approval was refused because its path is inside a source's checkout.
Those files name pages and paths. Written or read only outside every registered source root and the Git working tree holding it (mode 0600), they can never be synced, imported or committed.
Pass a path outside every source checkout, e.g. under ~/.gbrain.
The sweep's corpus pass stopped because the extraction model is not servable in this process; the captured session files stay pending (no .ingested sidecar), so nothing was lost.
No servable model is a state of the extracting process, not of the transcript. Before #6786 it was recorded as a finished file with zero facts, and retention later deleted the text.
Configure the extraction model (gbrain models shows it) or run the sweep from a process that has its key; the next sweep extracts the pending files. Run: gbrain models --json
agent
gbrain doctor --json
1
no
corpus_window_backoff
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A corpus window failed after its model call and waits out its retry delay (the next sweep, then 10, 20 and 40 minutes) before the sweep pays for it again.
Without a delay a write that fails after extraction (#6785) was paid for again on every drain.
Wait briefly, then retry the same request (writes: reuse the same request_id). Run: gbrain sweep --retry-failed --json
agent
repeat the read that failed
1
yes
corpus_window_dead_lettered
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A corpus window failed after its model call on every allowed attempt, so the sweep stopped paying for it; its file stays pending until an operator retries it.
A window that can never commit was re-extracted forever before #6785. The count is per window and source incarnation; tail growth and changing error codes do not reset it, and one extraction-config change (model, provider, key presence) retries it once.
Fix the cause the last code names (for writer_coordinator_required: gbrain sources writer status ), then ask the user before gbrain sweep --retry-failed --apply: the retry pays for the extraction again. Run: gbrain sweep --retry-failed --json
agent
repeat the read that failed
1
no
cost_cap_exceeded
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The run reached its cost cap before finishing.
The server failed; this is not a caller mistake.
Server-side failure, not a caller mistake. Run gbrain doctor --json on the brain host; if it repeats, report it to the user.
host_admin
gbrain doctor --json
1
no
cost_preview_requires_yes
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Cost preview requires yes.
The step needs the user's decision before it runs.
Stop and ask the user; re-run only with the authorization the message names.
user
repeat the read that failed
1
no
coverage_from
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The belief ledger does not cover that time for this page or source: it starts at the page's baseline cut or the source's watermark.
Recorded history exists only from a page's baseline (or creation) after the ledger was enabled; earlier times are unknown, not empty. A best-effort backfill from retained versions carries source times only, so it never answers a recorded-time read.
Ask about a time at or after the time the message names; gbrain beliefs status --source <id> lists the coverage intervals.
gbrain auth create or gbrain auth register-client was asked for a credential bound to no member on a brain that serves several people, so nothing was created.
A credential bound to nobody on such a brain is refused on every read (requester_scope_required); creating one would hand out a key that cannot work, or one that reads everyone's unmarked notes.
Bind it to the person it serves: gbrain auth create --member (gbrain access member list names the members). A shared agent passes --may-act-for instead; --reads-unscoped --yes creates one that reads every page no rule restricts for any asker, on purpose. Run: gbrain access member list --json
An unfinished managed sync cursor of this source was recorded under a source incarnation the source no longer has (it was re-pointed at a new checkout, or removed and added again), so no current sync selects or resumes it.
The cursor key digests the incarnation; every incarnation-joined reader drops the old rows while the local ledger mirror and the source-id-only cursor read still showed them. Retiring the bookkeeping says nothing about whether the current source's files are imported.
Preview gbrain repair managed-sync-orphans --source and apply it with the hash it prints; then gbrain sync status --source --json shows the current cursor, if any. Run: gbrain repair managed-sync-orphans --source '{source_id}'
Another maintenance cycle holds the brain cycle lock, so this run skipped instead of waiting.
Cycles serialize on the gbrain-cycle lease; the holder releases it when it finishes (or its TTL lapses after a crash).
Wait for the other cycle; unattended upkeep retries on its next turn (gbrain maintain --status shows the last skip).
agent
repeat the read that failed
1
yes
cycle_failed
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The maintenance (dream) cycle failed, or a phase threw and was contained so later phases could run.
The server failed; this is not a caller mistake.
Server-side failure, not a caller mistake. Run gbrain doctor --json on the brain host; if it repeats, report it to the user.
host_admin
gbrain doctor --json
1
no
d_sel_too_small
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The selection split has too few tasks for meaningful validation.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
database_error
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The brain database could not be reached or refused the operation.
The server failed; this is not a caller mistake.
Server-side failure, not a caller mistake. Run gbrain doctor --json on the brain host; if it repeats, report it to the user.
host_admin
gbrain doctor --json
1
no
deep_health_probe_failed
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The pooled SELECT 1 of /health?deep=1 did not answer: an earlier probe is still pending, it timed out, or it failed.
The deep probe runs through the ordinary pooled dispatch, where handler statements wait, so a saturated or wedged pool fails it while plain /health (a reserved idle connection) may still answer 200. One deep probe runs per engine at a time.
Retry in a few seconds; if it keeps failing, run gbrain doctor --json from a fresh process to check the database and pooler, then restart this gbrain serve.
Chunks of pages soft-deleted longer than the purge window (72h), which the purge would remove, are still stored.
Search never reads them; the purge lifecycle (gbrain pages purge-deleted, the autopilot purge phase) hard-deletes such pages and their chunks. Pages its holds keep (a derived retirement inside generations.restore_days, a restorable atom, an open rename-identity pair, a parked derived-page origin, an archived source) are not counted. The purge is brain-wide and irreversible, so it needs the user.
Preview with gbrain pages purge-deleted --dry-run --json, then run gbrain pages purge-deleted --yes once the user agrees. Run: gbrain pages purge-deleted --dry-run --json
A since/since_slug delta call reached more undelivered facts at one timestamp than that cursor can page; repeat the call with the opaque cursor.
The legacy cursor is a single timestamp, so facts that share one can only be paged by fact id, which next_cursor.cursor carries. Nothing was skipped and no cursor moved.
Repeat the delta call with the cursor from fix (next_cursor.cursor) instead of since/since_slug, and keep passing next_cursor.cursor afterwards.
Server-side failure, not a caller mistake. Run gbrain doctor --json on the brain host; if it repeats, report it to the user.
host_admin
gbrain doctor --json
1
no
demo_import_failed
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The fictional page did not import successfully.
The server failed; this is not a caller mistake.
Server-side failure, not a caller mistake. Run gbrain doctor --json on the brain host; if it repeats, report it to the user.
host_admin
gbrain doctor --json
1
no
demo_verification_failed
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Expected ownership or decision provenance is missing.
The server failed; this is not a caller mistake.
Server-side failure, not a caller mistake. Run gbrain doctor --json on the brain host; if it repeats, report it to the user.
host_admin
gbrain doctor --json
1
no
derived_cap_exhausted
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Paid work stopped at the cost cap derived from its estimate; the run is resumable.
The server failed; this is not a caller mistake.
Server-side failure, not a caller mistake. Run gbrain doctor --json on the brain host; if it repeats, report it to the user.
host_admin
gbrain doctor --json
1
no
destination_not_ready
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The destination brain is not initialized for this operation.
Only the operator of the brain host can change what blocks this.
Only the brain host's operator can resolve this. Tell the user the message and run gbrain doctor --json on the brain host.
host_admin
gbrain doctor --json
1
no
dirty_tree
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Commit or stash canonical skill edits before optimization.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
doctor_alert_act
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
gbrain doctor --alert found a page-class check that needs someone now (database unreachable, writes failing or stalled, migrations pending or wedged, more than one build running, sync or maintenance stalled, corrupt rows, a public schema exposed, or a tripped paid-loop breaker).
Only page-class checks page; skill, advisory and coaching checks never do, so health_score warnings alone exit 0. Each item in --json alert.items keeps that check's own fix, consent, actor and verify.
Read alert.items in the --json document and follow each fix.next; page the operator for items whose fix needs them. Run: gbrain doctor --alert --json
gbrain doctor --alert found nothing to act on, but at least one page-class check did not run fresh in this run, so the brain's health is unknown, not clear.
A check that timed out, errored, was reported from its last known result or was skipped by the tier proves nothing; reading it as healthy would hide an outage. alert.consecutive_unknown counts the alert runs in a row that ended unknown, and agent crons page on the second.
Run each alert.unknown item fix (it measures that check alone); if a check keeps running out of time, raise --budget-ms or run gbrain doctor --alert --tier standard --json. Run: gbrain doctor --alert --budget-ms 0 --json
The remote serve cannot answer this doctor tier or check for this client, so the thin client ran nothing.
A serve older than the doctor ops tier does not advertise run_doctor's tier and only parameters or get_brain_health, and a token without admin scope cannot call run_doctor; the thin client never falls back to the full report.
Only the brain host's operator can resolve this. Tell the user the message and run gbrain doctor --json on the brain host. Run: gbrain doctor --tier ops --json
Writes deferred behind a worktree refresh are still waiting, and an older gbrain cannot drain them.
A release before the refresh write barrier never claims a deferred write, so after a downgrade those writes wait until the next upgrade. Safety does not depend on this check; liveness does. A released write publishes only when a gbrain process runs the write consumer on the worktree's owner host; polling its receipt does not publish it.
Turn the barrier off (gbrain config set persistence.refresh_barrier false); wait until gbrain upgrade --check-downgrade exits 0, then downgrade.
The commit notifier did not wait on a source's drain lease because the process holding it has made no commit or cursor save for 5 minutes; it counts as a failed attempt.
Waiting on a holder that commits nothing kept the source due forever with nothing reported. Counting it as a failed attempt runs the notifier's retry tiers (5 s, 15 s, 1 min, 5 min), so the source reaches notifier_stalled with the sync-now fix in sync status and doctor; a foreground sync follows the holder and takes the source over when its lease lapses.
Read gbrain sync status --source --json (the notifier block and drain_holder name the holder), stop that process if it is wedged, then run gbrain sync --source --no-pull.
A managed sync drain stopped blocked because its head write made no progress (no committed receipt and no step advance) for the whole stall window.
A renewed lease is not progress: the detector keys on the head claim's phase and step. With a live owner on this host the drain prints stalled <N>s on <step> from the allowance (budget plus 30 s) and keeps going; it stops only when persistence.preparation_ceiling_ms passes without the root being released, or when that owner's heartbeat row reads wedged (cause: owner_wedged_here, with the owner's kind, pid and nonce and retry_after_ms to the ceiling, after which the owner frees the root and the next pass holds the entry). A lapsed claim (owner_missing) stops at once unless this host owns the checkout and a live full consumer can reclaim it, which gets one more window. drain.stall.cause names which.
Inspect the writer with gbrain sources writer status --source --json (read-only: the owner process, its step and what it waits on, and the next action). Before the ceiling (next.safe_to_loop true) rerun next.command after retry_after_ms; past it, or with a wedged owner, restart the named owner process on the brain host and rerun the same sync. Run: gbrain sources writer status --source '{source_id}' --json
host_admin
gbrain doctor --only managed_sync_not_moving --json
A dream synthesize or patterns submission died (or, for patterns, was cancelled at its timeout after paid work) the breaker limit of times within 24 hours, so it was not submitted again.
A run that keeps dying keeps paying; the breaker stops resubmitting until the cause is fixed and the key is reset. Patterns count per source (dream:patterns:source:<id>) whatever reflections each run read, and a completed run resets that count.
A required capability is not available on this brain. Run gbrain doctor --json to see what is missing. Run: gbrain doctor --only dream_paid_loop --json
Only a failed, non-running embedding effect can be explicitly retried.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
embed_backfill_stalled
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A source's automatic embed-backfill failed the same way several times with nothing embedded, so automatic backfill for it backs off and then stops.
The only remaining work sits on pages whose text projection cannot be rebuilt (a rebuild_failed projection, or an image page: gbrain projections drain seals the importer-attested ones, the rest need their importer). Each identical run spent a worker slot and dead-lettered; after three, automatic submission stops until the blocked pages or the stale chunks change, or a run embeds something (#6803). Explicit gbrain embed --stale and gbrain jobs submit embed-backfill are not gated.
Run gbrain doctor --only embed_backfill_stalled to see the blocked pages, preview the repair with gbrain projections drain --dry-run, then run gbrain projections drain; it names each page that still fails and its next step, and gbrain doctor --only text_projection_readiness --json counts the image pages by class. Run: gbrain doctor --only embed_backfill_stalled --json
openEngine (gbrain/engine-open) was called without embedded_core: true, so no engine was opened.
Opening an engine from settings alone is an experimental embedding surface that is off by default; a host opts in explicitly so no existing caller changes behavior.
Pass embedded_core: true in the settings; the CLI, gbrain serve and mounts open brains through their own connect path and need nothing.
An operation that serves an embedding host (file_register, file_verify) was called on an engine the CLI or a server opened, so it did nothing.
These operations trust a host that stores bytes itself; a brain opened the usual way stores files through file_upload, so the operations stay off there and its behavior is unchanged.
Call it on an engine opened from settings with settings.storage; a brain the CLI or a server opens stores files only through file_upload (gbrain files upload).
The embedding migration cap is below its worst-case cost; nothing was changed.
A capability this request needs is not configured or not reachable on this brain.
A required capability is not available on this brain. Run gbrain doctor --json to see what is missing.
agent
gbrain doctor --json
1
no
embedding_configuration
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The brain's embedding configuration is invalid.
Only the operator of the brain host can change what blocks this.
Only the brain host's operator can resolve this. Tell the user the message and run gbrain doctor --json on the brain host.
host_admin
gbrain doctor --json
1
no
embedding_disabled
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Embeddings are disabled on this brain.
A capability this request needs is not configured or not reachable on this brain.
A required capability is not available on this brain. Run gbrain doctor --json to see what is missing.
agent
gbrain doctor --json
1
no
embedding_failed
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Computing embeddings for the content failed.
The server failed; this is not a caller mistake.
Server-side failure, not a caller mistake. Run gbrain doctor --json on the brain host; if it repeats, report it to the user.
host_admin
gbrain doctor --json
1
no
embedding_identity_unqualified
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The brain's embedding_model config row names a model with no provider prefix, so managed fact extraction cannot verify its embedding identity.
Rows from older installs stored the bare model name. The managed facts resolver reads only the DB row and config set refuses to change it, so the supported rewrite is gbrain migrate embeddings --to <provider:model>, which re-embeds active facts (paid).
Preview the rewrite with gbrain migrate embeddings --to <provider:model> --dry-run, show the user its cost, and apply it only with their paid authorization. Run: gbrain doctor --only embedding_identity_unqualified --json
Embedding policy or claim storage is temporarily unavailable.
A temporary condition (a lock, a pending write, a rate limit); the same request can succeed later.
Wait briefly, then retry the same request (writes: reuse the same request_id).
agent
repeat the read that failed
1
yes
embedding_unavailable
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The provider returned an incomplete embedding batch.
A capability this request needs is not configured or not reachable on this brain.
A required capability is not available on this brain. Run gbrain doctor --json to see what is missing.
agent
gbrain doctor --json
1
no
embedding_unconfigured
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The selected brain has no verifiable text embedding model and dimensions.
Only the operator of the brain host can change what blocks this.
Only the brain host's operator can resolve this. Tell the user the message and run gbrain doctor --json on the brain host.
host_admin
gbrain doctor --json
1
no
embedding_width_mismatch
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The embedding model cannot produce the width of the brain's vector column; nothing was changed.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
enforced_member_refused
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The CLI runs under GBRAIN_ENFORCED_MEMBER and refused the command before it read or changed anything: the command or its arguments are not on the enforced member allow-list, the variable names no usable member, a target page or source is outside what the member reads, the write would change an access or privacy label, or the brain turned member writes off (access.enforced_member_writes).
A launcher pins GBRAIN_ENFORCED_MEMBER so a shared agent turn acts as one member: reads show only what that member reads, writes never touch a page it cannot read or change a label, and anything not classified is refused rather than run as the trusted owner. Stderr starts with gbrain: refused under GBRAIN_ENFORCED_MEMBER=: [GBRAIN_ENFORCED_REFUSED].
Do not retry here; nothing was changed. Ask the brain owner to run the command in a direct session, one without GBRAIN_ENFORCED_MEMBER.
The brain's engine does not implement the capability this call needs (reason names it), so the call was refused before any work and nothing was written.
The Rust engine preview grows one capability at a time. A call that needs a capability it does not report is refused up front instead of running part of the way; detail names the member, the capability and whether anything was written (written=nothing unless the outcome is partial or unknown).
Run the call on a pglite or postgres brain, or wait for a gbrain release whose Rust engine reports the capability.
The brain database was unreachable (the engine is in degraded mode), so background work such as unattended upkeep skipped this run.
A degraded engine answers from its last state and reconnects on its own; writing maintenance results then would be lost or refused.
Run gbrain doctor --json and report the connection problem it names.
agent
gbrain doctor --json
1
no
engine_embedding_mismatch
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
An engine opened from settings names an embedding model or width that differs from the one its database already records, so initSchema changed nothing.
The vector column has one width and the brain one embedding model; seeding another over it would make every stored and future embedding unreadable. Changing it is an explicit re-embed the user decides on.
Pass the database's recorded model and width in settings.embedding, or read the recorded identity with gbrain migrate embeddings --status on the brain host and preview a migration from there. Run: gbrain migrate embeddings --status --json
An engine opened from settings has no host identity, so nothing that needs one ran and no host.json was created.
An embedded engine publishes and claims work under the host id its host gave at open; minting a host.json under the home directory instead would tie its writes to whatever process happens to share that directory.
Pass host: { id: } to openEngine; keep the same id for the same host across restarts.
An engine opened from settings made an AI call (embed, chat, expansion or rerank) through a provider its settings.ai does not name, or after it was disconnected, so nothing was sent.
An embedded engine's AI calls reach only the providers and keys its host passed as values. Falling back to a process.env key, ~/.gbrain/config.json or the process-wide gateway would spend another brain's key and send this brain's text where its host never pointed it.
Pass the provider in settings.ai.providers (apiKey, and baseUrl when it is not the default) to openEngine, or point settings.ai.models (or settings.embedding) at a provider the engine has.
An AI call (embed, chat, expansion or rerank) ran outside any engine scope while this process holds engines opened from settings, so nothing was sent.
With no scope the call's brain is unknown. Using the process gateway, a process.env key or ~/.gbrain/config.json would spend a key no brain's host gave and could send one brain's text where its host never pointed it, so the call refuses whatever process gateway the host configured.
Run the call inside withEngineScope(engine, fn) for the engine it belongs to, or withLocalScope(fn) for a call that belongs to the process gateway (both exported from gbrain/engine-open).
A setting passed to openEngine is missing or malformed (engine kind, database url or path, pool size, host or writer id, writer credential or lane, embedding identity), so nothing was opened or registered.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the setting the message names and call again.
A schema pack in scope did not load, so the entity page types are unknown; onboarding's entity_link_coverage and timeline_coverage warn instead of grading the old hardcoded type list.
Entity types come from the active pack per source (the get_health predicate). Grading a fixed person/company list would count the wrong population on a pack with its own entity types, so the checks name the sources whose pack failed.
Run gbrain schema active --json (add --source for a named source) to see which pack is active and why it did not load; fix or reinstall the pack, then gbrain onboard --json.
agent
gbrain doctor --json
1
no
eval_suite_unwired
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
gbrain eval run-all was asked for a suite it does not run in-process (longmemeval or replay); nothing ran.
run-all runs only wired suites (brainbench). Recording a skipped run and exiting 0 would read as a completed sweep with no numbers behind it.
Run each requested suite with its own command (gbrain eval longmemeval <dataset.jsonl> --mode <mode> --record, gbrain eval replay --mode <mode>), once per mode, or drop it from --suites.
agent
repeat the read that failed
1
no
explicit_tasks_conflict
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
SkillOpt was given explicit task lists and a benchmark file; it takes one or the other.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
export_limit
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
This migration is bounded to 5,000 active pages per source; split or use a reviewed bulk export.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
extract_write_lost
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A link or timeline write lost during extraction (after the engine's own retries) left its pages unstamped, so they stay due; pages whose writes landed were stamped.
Stamping links_extracted_at for a page whose rows were dropped would hide the loss from every later extraction; leaving it due lets extract --stale, or the cycle's stale drain, write it again.
Run the retry command the message names (gbrain extract --stale with the source id); it re-extracts only the pages still due. Run: gbrain doctor --only links_extraction_lag --json
agent
gbrain doctor --only links_extraction_lag --json
1
yes
extraction_failed
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The accepted atom extraction failed (malformed output, or a response stopped before the end); a new attempt needs approval.
The drain retries a failed managed atom batch on its own up to 3 times per content (then holds it, code held_failed); this code reports a failed explicit retry, or a failure the drain cannot attribute to a checkpoint, so the same input is not paid for again without approval.
Server-side failure, not a caller mistake. Run gbrain doctor --json on the brain host; if it repeats, report it to the user.
host_admin
gbrain doctor --json
1
no
extractor_identity_mismatch
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The approved extractor differs from the installed extractor; this receipt cannot resume or admit another revision.
The server failed; this is not a caller mistake.
Server-side failure, not a caller mistake. Run gbrain doctor --json on the brain host; if it repeats, report it to the user.
host_admin
gbrain doctor --json
1
no
fact_already_expired
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The fact had already expired before this write.
For forget_fact the withdrawal is still recorded first (the ledger row and the struck page row), so a later import cannot bring the fact back; any other write changed nothing.
Do not retry with the same fact id. List the active facts (recall) to find the current one.
agent
repeat the read that failed
1
no
fact_not_found
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Fact not found.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
fact_rows_collide
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Carrying a page's identity across a rename would drop facts: a fence row of the old page has a different claim in the new file, or the new file does not hold it.
gbrain repair rename-identity merges the two pages' facts only where both say the same thing at the same fence row; anything else would lose one side, so nothing is written.
Give each old claim its own row in the new file's facts fence (or keep the same claim at its row), commit and sync, then preview again; or keep the old page with gbrain restore, or release the hold with --close.
remember, or an owner gbrain trust release that writes a held fact into its entity page's ## Facts table (a managed brain), refused a claim that was explicitly forgotten for this subject (wire invalid_params, message prefix fact_withdrawn:); nothing was saved, and a refused release leaves the fact held.
A forgotten claim stays withdrawn: remembering the same normalized text does not restore it, and a claim forgotten without an entity is withdrawn for every entity. The additive withdrawn object (at, subject: an entity slug or all_entities, visibility) says when and how widely the exact claim was forgotten; it covers that exact claim only, and its absence carries no meaning.
Do not retry the same text. Tell the user the claim was forgotten (withdrawn.at, withdrawn.subject); if it is still true, remember it in new words. To link a fact saved without an entity, remember it with entity and replaces set to its fact id instead of forgetting it. For a refused release, do not retry it: drop the hold (gbrain trust drop h) unless the user wants the claim back in new words.
agent
repeat the read that failed
1
no
facts_absorb_write_refused
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Facts absorb refused the write.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
A page write queued no automatic fact extraction; the receipt's facts_backstop.skipped reason says why (a kind:<type> reason names a page type that is not extracted).
A capability this request needs is not configured or not reachable on this brain.
Nothing failed. opted_out means the page frontmatter sets facts_backstop: false; remove that line and save the page to extract it. Run: gbrain get --source '{source_id}' -- '{slug}'
The automatic facts drain left queued facts-absorb jobs waiting; reason says why and fix, when present, is the next step. Nothing is dropped: the jobs run on a later drain.
A capability this request needs is not configured or not reachable on this brain.
Read doctor facts_drain: its message names the cause and its fix the next step (raising a spend cap is paid; ask the user first). Run: gbrain doctor --only facts_drain --json
A facts-absorb job failed inside the automatic facts drain; it retries with backoff until its attempts run out.
The server failed; this is not a caller mistake.
Read doctor facts_drain: its message names the cause and its fix the next step (raising a spend cap is paid; ask the user first). Run: gbrain doctor --only facts_drain --json
A fact was not indexed from the facts fence row its request names because that row no longer reads back as the fact (removed, struck, emptied, another visibility or other text), or, for an owner release of a held row, because its context or source was edited after the hold (held_row_edited, named in the message); nothing was written, and a refused release leaves the fact held.
A facts row derives from its fence row, which Git holds. Indexing a fact at a row that now says something else would make the database disagree with the file, so the write stops and the file stays as it is. For held_row_edited the row still reads back, but the owner approved the older context or source, so indexing it would publish content the owner did not review.
Read the page (gbrain get ) to see the row as it stands; if the fact is still wanted, remember it again, which writes it as a new row. For a refused gbrain trust release, do not remember it and do not release the same hold again (it refuses the same way): drop it (gbrain trust drop h). If the edit was itself held, gbrain trust review lists it separately.
A legacy fact row was not adopted into its page's facts fence because the fence codec reads the rendered row back as something other than the stored fact.
The fence trims a claim, folds CRLF to LF, reads ~~x~~ as a struck row and <br> as a line break; a claim the codec would change by more than whitespace cannot be written into the fence without changing what it says, so the row stays a legacy row (active and searchable, nothing is lost) and is counted by doctor fence_integrity as unrenderable_legacy_facts. The same code names a planned adoption whose rendered fence does not read back as its facts; that is a gbrain planning defect, not caller input.
Nothing to fix in the page: the rows stay active and searchable. Report the page slug and the reason class with the gbrain version; do not forget or expire a row to clear this count. Run: gbrain doctor --only fence_integrity --json
A page's checkout file and its database copy differ, so the writer left both as they are instead of replacing one with the other; the item is held and the rest of the batch continues.
Replacing the file with the database copy (or the database copy with the file) would destroy an edit only the replaced copy holds: a hand edit sync has not imported, an unindexed file at the page's path, or a database edit the file never received (#6982). The file is replaceable only when it equals the live page or one of its recent page_versions rows.
If the file holds the newer edit, run gbrain sync --source to import it; if the database copy is newer, re-save the page with write-through on; when both changed, ask the user which version to keep before retrying.
A managed sync import would have overwritten a database version of the page that sync never saw (the page changed since its file was last imported), so the file is held and the page keeps the database version.
Sync imports a file only when the page is still at the revision its last recorded import wrote, or when the import changes nothing. Here the page moved (a database-only write, or no import record to compare on an upgraded brain) and the file's content differs, so importing would silently replace the newer database copy. Pages under storage.keep_db prefixes are never held: the keep_db worker reconciles them from the database.
Preview with gbrain repair file-drift --source --slug --prefer database (keep the database copy and rewrite the file) or --prefer file (import the file); the preview writes nothing and names any file edit or deletion sync never imported that the database copy would overwrite. Decide with the user: the apply needs their consent (run it without --yes to get the consent message, exit 3, and add --yes only after they agree). The next gbrain sync --source --no-pull re-screens the hold.
gbrain repair file-drift --held selected held pages of more than one Decision (side, or deleted state), so nothing was previewed: one --prefer must not resolve differently shaped drift in bulk.
Each side and deleted state is its own Decision with its own meaning of --prefer file and --prefer database; resolving them together would apply one choice to questions the user answered differently, or not at all.
Preview one Decision at a time with the narrower commands the message names (--held --side , plus --state for --side deleted), or narrow with --only / --skip. Run: gbrain sources status '{source_id}' --json
gbrain repair file-drift --held for deleted-side drift needs --state (tombstone_edited, purged_differs or file_gone); nothing was previewed.
In each deleted state --prefer file and --prefer database do opposite things (tombstone_edited: restore and import, or keep the deletion and remove the file; purged_differs: import as a new page, or remove the file; file_gone: soft-delete the page, or recreate the file), so the state is always named explicitly.
Rerun the preview with --side deleted --state , choosing the state gbrain sources status --json lists for the held files. Run: gbrain sources status '{source_id}' --json
The file is over the page size limit (24 MiB for a Markdown page, 5 MB for a code file), so it was not imported.
Every page under the limit is stored, chunked and searchable whatever its size; the limit bounds what one page may hold in this release. The same bytes refuse on every retry. A smaller page refused by an MCP or HTTP transport is a different refusal.
Leave the file out of the source (sync.exclude), or, if it must be in the brain, split it into files under the limit; then sync or import again. Never split a page under the limit.
Sync held one file because it is not a readable regular file inside the source root (a symlink, a non-regular file or a permission error); the rest of the source synced.
Sync reads only regular files inside the source root and never follows a symlink, which can point anywhere on the host. The file waits in the hold store instead of failing the run, so it never blocks the source, and classic sync re-screens it on every run.
Replace the symlink with the regular file (or delete it), make the file readable to the account that runs gbrain, or leave it out with sync.exclude; the next gbrain sync --source --no-pull re-screens it.
gbrain repair file-drift --prefer file refused a page because keeping its file would need a full re-render of the file, not only appended protected parts; nothing was written.
File wins keeps the canonical file's bytes and adds only what reconcile's protections keep from the database: protected frontmatter keys the file lacks and database-only timeline rows, appended. A result that also changes a value, a tag, the title or the body would re-render the whole file (keys reordered, lists re-emitted, rules and headings rewritten), which is not the file winning.
Show the user the page's exceptions in the preview. Commit the database-only differences into the file through the door (gbrain git commit-push) and preview again, or preview --prefer database if the database copy should win.
A gbrain lint fix was not applied because the file refused the write (EACCES, EPERM or EROFS); the file was left unchanged.
Lint repairs files in place, and this file's permissions or a read-only mount stopped the write; lint reports it and continues with the remaining files.
Make the file writable by the user running gbrain, or pass its directory or file name to gbrain lint --exclude, then lint again.
A table gbrain owns by name (an OAuth table) already exists in the brain's schema without a column gbrain always gives it, or with a type gbrain never gives it, so schema setup stopped before the schema replay or any migration changed anything; the message names the table, the column, the type found and the type gbrain needs.
gbrain creates its tables with CREATE TABLE IF NOT EXISTS, so without this check it adopted a same-named table another application created in the shared database, added its own columns to it and failed partway through an upgrade on the first statement that compared the wrong type (#9190). The table holds that application's data, so gbrain never moves, renames or drops it.
Ask the user: give gbrain its own database, or move the other table to a schema of its own (ALTER TABLE SET SCHEMA takes its indexes and constraints along) and point that application there; then run gbrain apply-migrations --force-schema --yes.
A caller asked to forget a fact (remote forget) or remove a take (takes_remove) more trusted than its own writes, so nothing was removed and the owner was asked instead.
Lower-trust writers cannot overwrite, supersede or forget what the owner confirmed or curated (#5575 guarded supersession). The request became a trust proposal the owner can accept on the brain host; forget's frozen expired meaning is unchanged because nothing expired.
Do not retry. Tell the user the fact or take needs their decision and give them the command in fix (gbrain trust confirm on the brain host).
user
repeat the read that failed
3
no
frontmatter_alias_limit
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A file an older gbrain imported nests YAML aliases in its frontmatter that expand past the size limit, so sync holds it alone.
#7018 bounds YAML alias expansion on purpose (a few hundred bytes of nested anchors expand into gigabytes), so refusing bytes an older gbrain imported is intended, not a parser regression: the page keeps its last imported version and the rest of the source syncs.
Reduce the alias nesting in the frontmatter (or write the values out), or remove the file, then commit and sync again.
agent
repeat the read that failed
1
no
frontmatter_slug_conflict
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The file's frontmatter slug: names a different page than its path does.
The path decides a file's page; a conflicting declared slug would overwrite or fork another page, so the file is refused until one of them changes.
Remove the slug: line or make it match the path, then commit and sync again.
agent
repeat the read that failed
1
no
full_resync_required
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The catalog cursor is invalid or expired.
A temporary condition (a lock, a pending write, a rate limit); the same request can succeed later.
Wait briefly, then retry the same request (writes: reuse the same request_id).
agent
repeat the read that failed
1
yes
gate_failed
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The eval gate found retrieval regressions or correctness below its thresholds.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
generation_fenced
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A derived result was not published because the live generation or its input changed after the producer read them; nothing was written.
The generation primitive (GBRA-161) publishes a result only against the generation and input pin it was computed from. A concurrent run that published first (stale_generation), or an input edited since the read (pin_moved), would otherwise let an older result replace a newer one.
Run the producer again; it reads the current generation and input and recomputes.
A derived result was recorded as held instead of published, so nothing it would have retired was retired.
A model-produced result at or below the input-relative shrink floor (shrunk), one over generations.max_items (oversize), one over the run window retirement budget (valve), an empty result without a proof the input is really empty (no_proof, fence_absent), repeated failed attempts on one input (attempts_exhausted) a segmented page the ledger cannot keep a copy of (segmented_unsupported) or a ranked result whose cut is ambiguous (tie) would retire live items on evidence the primitive does not accept (GBRA-161 D4/D5).
Preview the held set with gbrain repair generations --kind --mode release-held --held --since d. shrunk, valve and attempts_exhausted publish once with --apply --expect --yes after the user agrees; oversize needs gbrain config set generations.max_items first; no_proof, fence_absent, segmented_unsupported and tie clear only when the input or the producer result changes. Run: gbrain doctor --only generation_held --json
A derived generation was not activated because one of its items was not live at the content the publication wrote; nothing was committed.
Activation rechecks every item of the new generation under the key lock; an item another writer changed or deleted in between would make the ledger record a set that is not what the pages say.
Run the producer again; it reads the items as they are now.
gbrain repair ghost-pages refused to soft-delete more than half of a source's file-backed pages; nothing was changed.
The sync mass-delete valve (#2828) applied to ghost pages: that many missing canonical files almost always means the checkout is the wrong path, unmounted or half-cloned, not that the files were deleted.
Check the source checkout on its owner host first. If removing these pages is genuinely intended, ask the user, then rerun the same apply command with GBRAIN_ALLOW_MASS_RECONCILE=1. Run: gbrain sources writer status --source '{source_id}' --json
Ghost pages of a source cannot be classified because its canonical checkout cannot be read reliably; nothing was listed or changed.
A page is never reported or removed as a ghost while its file may only be unreadable: a missing or non-directory root (storage_unavailable), or a stat error, an invalid gbrain.yml or an inconclusive page check (ambiguous_storage), fails closed.
Inspect the source checkout on its owner host (writer status shows its root), fix it, then preview gbrain repair ghost-pages --source again. Run: gbrain sources writer status --source '{source_id}' --json
The canonical checkout's branch has no commit yet, so Git durability has nothing to build on.
A Git effect commits on top of HEAD and pushes the branch; on an unborn branch (a fresh init --git root) there is no HEAD to commit on and no ref to push, so enabling durability would park every effect. The database is unaffected.
Make the first commit on the branch on the brain host (git add -A && git commit -m "Initial brain"), then rerun gbrain sources writer git-durability --enable.
host_admin
gbrain doctor --json
1
no
git_checkout_required
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The canonical root is not inside a Git checkout, so its Git effects have nothing to commit to.
Only the operator of the brain host can change what blocks this.
Initialize the root as a Git repository with a first commit and a remote on the brain host, then rerun; a database-only source needs no Git durability.
host_admin
gbrain doctor --json
1
no
git_command_stopped
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A git command was stopped before it finished (its time limit, an output limit, a signal from outside gbrain, or git crashing on a signal such as SIGSEGV), so gbrain did not use its partial output.
The child ended without exiting on its own (unless it crashed, git itself works), and a cut-off listing read as the answer would stage, restore or report the wrong files.
Rerun the same command once. For a signal, check the machine first (the out-of-memory killer or a supervisor), or for a crash run git fsck on the checkout; if it stops again, tell the user which command and checkout.
Converting a source to git-canonical would discard database content or cannot place it, so the apply wrote nothing.
gbrain sources canonical --to git applies only when every database row will be in Git or in a declared database-only class afterwards. The preview counts what would be lost or cannot be placed by category (detail lists them): both_moved and held_drift_both, a page Git and the database both changed; no_record_both_moved and no_record_no_evidence, a page with no import record whose content history shows both sides moved, or shows nothing, until the owner's --decisions file decides it; deleted_in_git, a page Git deleted that the database edited since; uncommitted_edit, a working-tree edit the adoption would overwrite; ignored_target, a page whose file Git ignores without a declared class; unparseable and unsafe_path, a committed file or path sync cannot read; segmented_page, a segmented page conversion does not adopt yet; export_mismatch, a page whose export does not read back equal; git_overwrites_database, a page version a strict pass would replace that nothing accepted; ignore_status_unknown, a target whose ignore status Git cannot read (beyond a symlink, outside the checkout, a timed-out check). There is no override.
Relay the categories and their paths (the --dry-run preview lists them) and ask the user how each should be resolved; preview again afterwards.
An approved conversion found pages that changed since the approval, or decisions it did not approve, so only the unchanged pages were applied and the source stays mixed.
gbrain sources canonical --to git --apply --approved applies only the pages whose slug, revision, committed blob, evidence and action are the ones the owner approved. A page that changed since, a new page, a database edit the plan would now discard, and any decision the approval did not hold stay unapplied and are listed (delta) with counts; nothing outside the approved set is applied without a new decision.
Relay the delta list and its counts to the owner; once they decide, preview again with --approval-out and apply the new approval.
A git-canonical conversion stopped because its strict pass did not finish, finished with work left after the flag was set, or found the flag removed (a --to mixed apply) while it ran.
The conversion runs a full strict-equivalent pass before it sets canonical: git, and one genuine strict pass after, then up to three closing strict passes while only door commits a live writer landed meanwhile are left (Git ahead of the database). A pass that ends partial, blocked or deferred stops the conversion where it is: before the flag the source stays as it was, after it the source stays strict (Git wins) and the plan lists what is left.
Wait until gbrain sync status --source --json shows the source idle, then preview again with gbrain sources canonical --to git --dry-run and apply the new hash.
The canonical checkout is on a detached HEAD, so a push would target the wrong ref.
Only the operator of the brain host can change what blocks this.
Check out the branch the remote should track (git switch ) on the brain host, then rerun.
host_admin
gbrain doctor --json
1
no
git_durability_not_enabled
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A filesystem source's owner will not commit or push its page writes (Git durability is off, or not recorded and no harden post-commit hook is installed), so its Git effects complete as skipped; writer activate still proceeds and lists it under warnings.
Activation applies the effect runner's own policy: the binding's recorded setting decides, and only when nothing is recorded does the legacy hook decide (a failed probe counts as not durable). sources harden is refused once the brain is managed, so the recorded setting is the way to turn durability on.
Preview gbrain sources writer git-durability --enable --dry-run on the owner host, then apply it with --admin-intent writer_git_durability; enabling re-queues the Git effects that were skipped while it was off.
A git-canonical source would store content in the database without a file in Git; nothing was written.
On a source with canonical: git, page content reaches the database only after Git commits its file. The declared database-only classes (private, alias-private and lineage-private pages, storage.db_only directories, never-filed derive-phase pages, paths Git ignores, detached pages and origin twins) are the only exceptions. no_file_form: the write has no file and is in no declared class; declared_target: a publication would commit a file for a declared page; facts_lane: a writer with no file form yet, or a fact for a page-less entity under an exact page rule, which no holding page can carry (create the page with put_page, then remember again).
Ask the user which git home to configure (a path Git tracks, or a storage.db_only directory in gbrain.yml), then submit the write again with a new request_id.
A strict (canonical: git) write found a staged change of its path that is not committed, so it committed nothing and left the index as it was.
The door commits a path only while the checkout's index entry for it equals HEAD's. Committing over a staged change would overwrite it in the index or publish it under a gbrain commit, so the person who staged it decides first.
Commit the staged change, or unstage it (git restore --staged --
user
repeat the read that failed
1
no
git_index_locked
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Another Git process holds the canonical checkout index lock.
A temporary condition (a lock, a pending write, a rate limit); the same request can succeed later.
Wait briefly, then retry the same request (writes: reuse the same request_id).
agent
repeat the read that failed
1
yes
git_index_stale
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Git index stale.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
git_lfs_not_enabled
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A git-canonical write falls under a Git LFS rule, but storage.git_lfs is off or the checkout does not configure the LFS filter; nothing was written.
The door commits a file before its database row. A path .gitattributes routes through Git LFS commits as an LFS pointer only when the checkout configures the LFS filter (git lfs install --local) and the operator opted in; otherwise the raw bytes would be committed.
Ask the user: configure git-lfs in the checkout and run gbrain config set storage.git_lfs true, or narrow the .gitattributes rule; then submit again with a new request_id.
A committed file's Git object is missing from the checkout and its working-tree copy differs or is gone, so managed sync holds that file alone; a partial clone that lacks a tree of the synced commit stops the run.
An interrupted gc, a partial clone without its promisor remote or disk corruption can drop an object a commit still names. Sync imports the working-tree bytes when they hash to the committed blob id; otherwise it imports nothing from a guess, and the rest of the source keeps syncing.
In a partial clone (git clone --filter), which sync never fetches from, fetch the blob with git cat-file -p in the checkout or check the file out, or, when the run stopped on a missing tree, run the git ls-tree -r -d it names; otherwise run git fsck in the checkout to see what is missing and restore it with git fetch (a shallow clone) or from a backup. Then sync again; every sync re-tests the hold.
A git-canonical source refused to commit the file of a private, alias-private or lineage-private page; nothing was written and HEAD is unchanged.
Private pages of a source with canonical: git are database-only: their bytes never enter Git history. A page turning private is published as the door commit that removes its file, never as a commit of its bytes.
The page stays database-only. Write it through put_page (which publishes a private page without a file), or remove visibility: private if it belongs in Git, then submit again with a new request_id.
A write reached a git-canonical source from a process that does not declare the git-canonical protocol (an older gbrain, or gbrain.write_sources set by hand); nothing was written.
Only the operator of the brain host can change what blocks this.
Upgrade or stop the gbrain process that wrote it (gbrain upgrade on its host), then retry with a new request_id.
The canonical commit is durable locally; its push will retry.
A temporary condition (a lock, a pending write, a rate limit); the same request can succeed later.
Wait briefly, then retry the same request (writes: reuse the same request_id).
agent
repeat the read that failed
1
yes
git_target_changed
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A strict (canonical: git) write's file changed on disk while it was being committed, so nothing was committed and the write was not published.
The door commits exactly the bytes the write published, and checks the file's hash against them before and after Git stores it. An edit landing in between would otherwise be committed while the database records other content; recovery leaves the changed file as it is.
When the file holds neither the write's bytes nor the version before it, the write is held in recovery (blocked reason unexpected_file_bytes) and the source's later writes wait behind it; when it holds the version before the write, nothing is held and the write failed; when it holds the write's own bytes again by the time recovery runs, recovery restores the version before the write and the write failed, with nothing held. After a failure, read the page before resubmitting it with a new request_id. To resolve a held write, preview with gbrain repair stuck-recovery --source --json, ask the user which version to keep, then run gbrain repair stuck-recovery --source --keep disk|prior --apply --expect --yes (disk keeps the edit). Run: gbrain sources writer status --json
user
repeat the read that failed
1
no
git_target_ignored
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A .gitignore rule excludes the canonical file, so its Git effect cannot commit it; the effect parks at once.
The request itself was wrong or no longer matches the brain; nothing was changed.
Remove or narrow the rule and commit that change, then run gbrain sources writer retry-effects --parked-code git_target_ignored; or keep the file out of Git and leave the effect parked.
agent
repeat the read that failed
1
no
git_target_pending
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Git still lists a removed canonical file in the index; the removal was not committed yet.
A temporary condition (a lock, a pending write, a rate limit); the same request can succeed later.
Wait briefly, then retry the same request (writes: reuse the same request_id).
agent
repeat the read that failed
1
yes
git_target_unsafe
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Git cannot identify the existing canonical file by its native spelling.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
git_unavailable
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A git command did not complete.
A temporary condition (a lock, a pending write, a rate limit); the same request can succeed later.
Wait briefly, then retry the same request (writes: reuse the same request_id).
agent
repeat the read that failed
1
yes
git_worktree_link_broken
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The directory is a linked Git worktree whose link to its repository is broken (the repository's entry was pruned, or the checkout moved), so it cannot be claimed as a canonical worktree; nothing was claimed.
A linked worktree reaches its commits through a .git file naming an entry in the repository, and the repository names the worktree back. With either link broken, Git commands in the directory fail or the next git worktree prune deletes the entry, so a door commit would go nowhere.
From the repository, run git worktree repair on the worktree when both still exist, or add the worktree again with git worktree add, then rerun the claim.
host_admin
gbrain doctor --json
1
no
gitlink_not_followed
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A classic sync range added a gitlink (a submodule or an embedded repository); sync does not follow it, so the linked repository's files are not indexed.
A gitlink records another repository's commit, not files, and that repository may be absent or uninitialized. The rest of the source syncs; the notice (gitlinks_not_followed in the result and one stderr line) comes once, in the run that passes the gitlink.
Nothing is blocked. To index the linked repository, check it out and add the checkout as its own source (gbrain sources add --path ).
A managed sync pass ran under a grant that covers only part of the source, so it admitted what the grant can see and cannot finish (stamp) the source.
A slug-fenced grant never stamps a pass (design v3.2 §5): converging the whole source needs a writer that can see every page, which is the owner host's own sync.
On the host that owns the source, run gbrain sync --source --no-pull; check the result with gbrain sync status --source --json.
Server-side failure, not a caller mistake. Run gbrain doctor --json on the brain host; if it repeats, report it to the user.
host_admin
gbrain doctor --json
1
no
guest_attribution_missing
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A write to a guest source carried no valid guest attribution (the X-Gbrain-Guest header or request-level _meta.guest with sender_label and group); nothing was written.
The request itself was wrong or no longer matches the brain; nothing was changed.
Send sender_label and group in _meta.guest or the X-Gbrain-Guest header, then save with a new request_id.
A hook entry looks like gbrain's harness hook but is not this install's exact command, so gbrain left it in place.
An unmarked entry is deleted only when its command is exactly what this install (or its receipt) wrote; an edited command or another install's launcher is never removed, and removal is not reported complete while it remains.
Correct the request using the message above, then retry. Run: gbrain bootstrap harness --status
The queued write at the head of a managed source cannot be claimed by any consumer, and its blocker needs an operator; a managed sync drain stops drain_stalled with cause: head_blocked and blocked_by names the predicate.
#6543: the drain used to wait the whole no-progress window and print a constant claimable here: no. The head probe evaluates each predicate of the claim query for the head itself. Only intervention-required blockers stop the drain, after one governor tick of confirmation: a refresh fence no refresh process holds, or a running request ahead held by a process that reports restart_required. Live blockers (a foreground publication, a lapsed lease, a refresh or recovery making progress) keep the progress-aware wait.
Run next.fix: for refresh_fence resume the refresh (gbrain sources refresh --resume); for zombie_publication restart the named gbrain process on the brain host. Then rerun the same sync. Run: gbrain sources writer status --source '{source_id}' --json
A managed atom origin (a page or transcript) failed atom extraction 3 times on the same content, or its atom write did not commit 3 times, so the drain stopped retrying it; doctor extract_atoms_held_failed lists it with its last request id.
Every automatic attempt is a paid model call. After MAX_DETERMINISTIC_FAILURES completed failures of one content the origin leaves the atom backlog instead of being paid for every cycle; a batch whose write did not commit is struck each time the drain meets it, with no model call, and held at the same bound (#7514). Editing the content starts a new count, and an explicit retry runs it again.
A required capability is not available on this brain. Run gbrain doctor --json to see what is missing. Run: gbrain doctor --only extract_atoms_held_failed --json
agent
gbrain doctor --json
1
no
held_out_overlaps_benchmark
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Held out overlaps benchmark.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
held_out_required_for_bundled
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Held out required for bundled.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
hook_session_cwd
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A gbrain hook or stdio MCP entry (setup, the turn-rule lane, gbrain bootstrap's lanes) starts gbrain in the session's directory, or the hook launcher it names would not run.
Script-mode gbrain is a Bun script, and Bun runs the working directory's bunfig.toml preload and loads its .env before gbrain starts; harnesses run hooks and stdio MCP servers in the session directory, so a cloned repository could run code on every prompt or session.
Correct the request using the message above, then retry. Run: gbrain doctor --only harness_wiring --json
This process's host.json identity differs from the identity that owns the binding although both resolve on this machine, so writes that need the owner read it as another host.
Host identity is a file under the persistence home: a job worker or container launched with a different HOME or GBRAIN_HOME mints a new host.json and sees the binding as another host's (owner_unavailable, host_mismatch), so its maintenance writes never reach the owner. The check names both files and the environment each was minted under (minted_under, unknown for a file minted before it was recorded); re-deriving the identity would re-own every existing binding, so the fix is the environment, never the file.
Set GBRAIN_HOME on the supervisor of the process to the owner's home (the value the check prints; config appends .gbrain itself) and restart it; never edit or delete a host.json. Run: gbrain doctor --only host_identity_mismatch --json
host_admin
gbrain doctor --only host_identity_mismatch --json
The brain host is older than this client and did not answer the question asked: a get_page reply to an as_of read came back without valid_time.as_of, so it is the current page, not the edition in force on that date. Nothing historical was printed.
An older host ignores a read parameter it does not know and answers the plain read. Printing that answer as the edition in force on a date would quote the wrong text, so the client fails closed. The error carries the client version, the host version when known, and the minimum host version.
Upgrade gbrain on the brain host (gbrain upgrade), or ask its operator to; then run the same read again.
gbrain sources host-repo starts a hosted repository only for an empty, unbound source and an absent or empty directory; nothing was created.
The verb makes a new bare repository the source of truth for the source. Existing pages or an existing directory would need converting into it, which is a separate step, so it refuses instead of guessing.
Pick a new source ID and an empty directory, or keep this source as it is.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
invalid_fence
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A facts or takes fence in the page cannot be imported without dropping or guessing rows, so the page (or the file) was not written.
Facts and takes fences are the page's structured rows. Importing a fence that does not parse, repeats a marker or reuses a row number would silently drop or renumber rows, so coordinated writers refuse it and managed sync holds the one file while the rest of the source syncs.
A refused write: fix the fence the message names (fence, section and rows; the reason says what is wrong) and send the page again with a new request_id, or write rows with remember / takes_add. A held file or stored page: the maintenance run repairs it; preview it now with gbrain repair fences --source on the brain host.
The file's YAML frontmatter cannot be read without guessing, so it was not imported.
gbrain imports frontmatter it can read exactly (quoting an unquoted value at most). Guessing could store a wrong title, merge a duplicate, or read a protected key such as visibility as a broader value.
Fix the named line in the file (one line per key, the whole value quoted), then commit and sync or import again.
submit_agent over the local CLI: use gbrain agent run instead.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
invalid_source
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The source argument or source state is invalid for this operation.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
invalid_source_pin
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The .gbrain-source pin names an invalid source id.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
invalid_source_uri
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The page has a stored file source_uri that cannot be resolved to a local filesystem path.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
invalid_token
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The bearer token is missing, invalid, or revoked.
Only the operator of the brain host can change what blocks this.
Only the brain host's operator can resolve this. Tell the user the message and run gbrain doctor --json on the brain host.
host_admin
gbrain doctor --json
1
no
invalid_write_wait
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Invalid write wait.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
ipc_path_too_long
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The brain's local IPC socket path is longer than the operating system allows, even after the per-user run-dir fallback, so hooks and local commands cannot reach gbrain serve.
A Unix-domain socket path must fit sockaddr_un (107 bytes on Windows afunix, 103 on macOS); on Windows a long PGLite data-dir path already moves to %USERPROFILE%.gbrain\run, and only a profile path too long for that is reported.
Stop gbrain serve, move the brain to a shorter path (gbrain config set database_path <shorter path> after moving the data directory), then restart serve. Run: gbrain doctor --only ipc_socket_path --json
Most items of one per-item loop failed (or many failed with one code, or none succeeded), so the failure is systemic and no item was held; the unit stopped instead of skipping every item.
A per-item loop holds a bad item and continues (GBRA-130), but a run where most items fail points at a shared cause, and holding every item would hide it.
Fix the shared cause the first failures name, then rerun the same command; run gbrain doctor --json if the cause is unclear. Run: gbrain doctor --json
agent
gbrain doctor --json
1
no
keyword_candidates_incomplete
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Hybrid search's keyword arm returned a bounded result on a large corpus (the CJK arm's deadline or candidate cap, or a common-word match ranked from a sample), so some keyword matches can be missing.
The CJK fallback is an unindexed LIKE scan, and a query whose words match hundreds of thousands of chunks ranks a bounded sample of them (an OR retry also keeps only its rarer words); each bound keeps a large brain from stalling every hybrid search. An incomplete keyword search is not evidence of absence.
Add a rarer word or an exact "phrase", or narrow the search with --source-id (MCP source_id) or --types; for CJK text, ask the user to raise search.cjk_keyword_deadline_ms. Run: gbrain config get search.cjk_keyword_deadline_ms
Hybrid search's Postgres keyword arm skipped a statement that hit the keyword statement timeout within the negative-cache TTL; the search reports keyword_arm_failed with reason skipped_after_timeout and the vector arm still answers.
Running the same broad keyword statement again would hold a backend for the whole search.keyword_statement_timeout_ms and fail the same way. The skip covers that exact statement and scope only, lasts at most search.keyword_timeout_negative_cache_seconds (default 600, 0 turns it off), ends as soon as a background re-run of the statement in the serve answers, and is per serving process. A skipped keyword arm is not evidence of absence.
Narrow the search (source_id, types, since or until) to run keyword search now, or wait for the entry to expire; the user may raise search.keyword_statement_timeout_ms or change the TTL. Run: gbrain doctor --only keyword_plan --json
Retired: an older gbrain stopped a managed sync that kept re-freezing a page cancelled only because another page of the same sync did not commit. This build never cancels a page for another page's failure, so the stop is superseded.
Since #6712 each page of a sync has its own fate: a page that does not commit is held or stops the run on its own, and the pages after it still publish. A ledger row or receipt with this code was written by an older build.
Rerun the same plain gbrain sync --source --no-pull; it resumes the stopped entry under a fresh request. gbrain sync status --source --json shows what remains. Run: gbrain sync status --source '{source_id}' --json
A change to the page was recorded before the requested instant but was not yet proven committed at it, so the page at that instant cannot be stated.
A write's recorded time is a lower bound on when it became visible; until its commit mark (or a later write to the same page) proves it committed by the instant, the page then may or may not have included it.
Ask about an instant before the write was recorded, or after it was observed committed (the message names both).
A label-only repair left a page unchanged because its file holds the page but cannot take the label edit line by line.
Operator label repairs (gbrain repair visibility, gbrain repair private-labels) change only the label lines of a page's file and never re-render it, so a person's formatting, key order and comments survive. A label line with a block or multi-line value or a duplicate key, a file with no frontmatter block, or a file that still differs from the page once its label lines are edited (a frontmatter key, the title, the type, the tags or the body; never a stamp gbrain keeps only in the database) cannot be edited that way. The repair counts the page as declined, writes nothing, and the next preview lists it as held with what blocks it.
Make the field the refusal names in the page's file match the page, or write the label line as one plain line, commit it, run gbrain sync for the source, then preview the repair again.
gbrain pglite-repair --legacy-lock refused to move a legacy PGLite lock aside: a process on this host still uses the data dir, the data dir is on a network or shared filesystem, or gbrain could not confirm the filesystem is local.
The evidence the repair reads (kill -0, the process command, an open-file scan) covers only this host and PID namespace. A process that still holds the data dir, or a filesystem other hosts can mount or whose locality cannot be confirmed (neither Linux nor macOS, a failed probe, an unrecognised type, a macOS mount without the local flag), means the old owner may still be writing, and removing its lock would let two writers corrupt the brain.
Stop the process the message names (on a shared filesystem: every gbrain on every host that mounts it), then preview again with gbrain pglite-repair --legacy-lock --dry-run. For filesystem_unverified, run the repair on a Linux or macOS host where the folder is on a local disk; elsewhere only the user can confirm no gbrain on any computer reaches the folder and move the lock folder aside.
gbrain repair legacy-twins refused to merge legacy twin pairs that are more than half of a source's file-backed pages; nothing was changed.
The sync mass-delete valve (#2828) applied to legacy twins: each merge soft-deletes a file-backed twin, and that many twins at once almost always means a re-import under another slug fold or the wrong checkout, not a backlog of forked pairs.
Check the source and its checkout on the owner host first. If merging these pairs is genuinely intended, ask the user, then rerun the same apply command with GBRAIN_ALLOW_MASS_RECONCILE=1. Run: gbrain sources writer status --source '{source_id}' --json
Legacy twin pairs of a source cannot be checked because its canonical root is missing or is not a readable directory; nothing was listed or changed.
Whether a twin's file is still there and agrees with it is only known from the checkout, so the repair fails closed rather than merge on a guess.
Inspect the source checkout on its owner host (writer status shows its root), fix it, then preview gbrain repair legacy-twins --source again. Run: gbrain sources writer status --source '{source_id}' --json
A get_links / get_backlinks cursor was not one this listing returned: it belongs to another slug, direction, source scope or filter set, or is not a cursor.
A cursor is a link-id position bound to the exact listing that issued it; continuing a different listing from it could skip or repeat edges without saying so. Nothing was read.
Restart the listing with the same slug and filters and no cursor, then pass each next_cursor unchanged. Run: gbrain links '{slug}'
agent
repeat the read that failed
1
no
link_dates_unattributed
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
add_link or remove_link would re-create or change a links section whose dated statements were stored before each row kept its own dates, and gbrain cannot tell which row each date belongs to; nothing was changed.
Each row of a page's links section (target, type, source) keeps its own valid_from and valid_until. Statements stored before that have no source: with several rows for one target and type, or dates that do not fit the one row, any pairing would be a guess that could put one row's dates on another.
Add the page's ## Links section back with edit_page, one row per source with that row's own valid_from and valid_until, then submit the request again.
agent
repeat the read that failed
1
no
Reasons: several_rows, dates_do_not_fit.
local_conflict
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A local file or registration conflicts with the requested change.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
lock_busy
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Another process holds the lock this command needs.
A temporary condition (a lock, a pending write, a rate limit); the same request can succeed later.
Wait briefly, then retry the same request (writes: reuse the same request_id).
agent
repeat the read that failed
1
yes
loops_extraction_skipped
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A Google sweep or the managed catch-up queued no paid loop extraction; the sync summary's skipped_reason says why. Nothing failed and the email pages still imported.
Extraction is gated before any model call: a kill switch, a missing chat provider, the day's spend cap (loops.extraction_max_usd_per_day, default $2.00; spend_cap_zero means the user set it to 0), or an exclusion label (g_loops_exclude_labels / loops.extraction_exclude_labels) that did not resolve against the account's labels, which fails closed until a sweep resolves it.
Read the reason. daily_spend_cap clears at the next UTC day or when the user raises loops.extraction_max_usd_per_day; excluded_label_unresolved names the label token to fix in gbrain sources status <id> or gbrain config get loops.extraction_exclude_labels; the threads are extracted on their next touch or by gbrain sync --source <id> --full. Run: gbrain sync status --source '{source_id}' --json
agent
gbrain config get loops.extraction_max_usd_per_day
Managed maintenance stopped admitting requests because this writer's outstanding requests, reserved receipt bytes or permanent request ids would pass 80% of their limit; nothing more was submitted.
Each page of a maintenance run publishes as its own request under the local CLI writer the user's own CLI writes share. Stopping at 80% leaves room for those writes: reserved receipt bytes free only when receipts compact, request ids never.
Wait briefly, then retry the same request (writes: reuse the same request_id). Run: gbrain sources writer status --source '{source_id}' --json
Free unattended upkeep is off on this brain (maintenance.auto is false), so nothing ran.
The person turned upkeep off; doctor reads it as off, not stale.
Turn it back on with gbrain config set maintenance.auto true.
agent
repeat the read that failed
0
no
maintenance_lock_busy
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A source-scoped dream cycle skipped its brain-wide phases because another cycle (usually autopilot maintenance) holds the shared gbrain-cycle lease; its source phases still ran.
Brain-wide phases (synthesize, patterns, embed, purge and the other mixed or global phases) must not run twice at once, so a cycle that cannot take gbrain-cycle runs only the phases its own source lease covers.
Nothing is lost: the holder runs those phases itself. To run one now, wait until the lease is released, then re-run gbrain dream --phase <phase> (LLM-backed phases spend; ask the user first). Run: gbrain status --section locks --json
An autopilot keeps this brain maintained (its brain-wide pass stamped autopilot.last_global_at within 48 hours), so free upkeep did nothing.
One owner per brain: the autopilot already runs the free phases and more, on any host sharing the database.
Nothing to do; gbrain autopilot --status shows the daemon.
agent
repeat the read that failed
0
no
maintenance_owned_by_serve
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A live gbrain serve owns this brain and runs free upkeep while idle, so the scheduled upkeep run did nothing (serve owns upkeep).
One runner at a time: the serve holds the brain (the PGLite lock, or the warm CLI socket on Postgres) and runs the same free upkeep on its idle tick.
Nothing to do; gbrain maintain --status shows the last run and its runner.
agent
repeat the read that failed
0
no
managed_failure_unsettled
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The recorded managed sync failure is not settled by the imported state, so it was not acknowledged.
Acknowledging removes a failure record only when the file it failed on is already imported unchanged (or deleted in both the commit and the brain); anything else would hide content that never reached the brain.
Resume or retry the sync the failure names (gbrain sync status --source --json shows it), then acknowledge again if the record remains.
agent
repeat the read that failed
1
no
managed_pull_skipped
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The managed pull was skipped.
A temporary condition (a lock, a pending write, a rate limit); the same request can succeed later.
Wait briefly, then retry the same request (writes: reuse the same request_id).
gbrain repair rename-identity cannot carry a page identity on a managed source; nothing was written.
On a managed brain page tables change only through coordinated publications, and the carry is a classic-source maintenance transaction, so on a managed source the remedy can only close the pair.
Release the purge hold without carrying identity: preview gbrain repair rename-identity --source --slug --close, then run the apply command it prints after the user agrees; or keep the old page as its own page with gbrain restore --source-id --force.
A managed source refuses --skip-failed and --include-gitignored, and a strict (git-canonical) source also refuses --working-tree: managed sync keeps every failed-receipt and ignored-file guard and a strict source indexes commits only, so the run was refused before anything ran.
--skip-failed would acknowledge a failed receipt instead of retrying it, and --include-gitignored would import files Git ignores; neither has a managed meaning. detail names the flag.
Rerun the same gbrain sync command without the named flag; fix a failed file and the plain sync retries it, or commit an ignored file to sync it. Run: gbrain sources status --json
A managed source has unfinished sync work and a live consumer on its owner host, but no committed managed_sync_* receipt and no head step advance for longer than persistence.preparation_ceiling_ms.
Process liveness is not data movement: /health ok, a live pid and sync_running: true all held while one deployment moved nothing for weeks. sources status --json carries data_moving, not_moving_since and movement_state per source (parked when no drain or full consumer is live, informational), doctor warns with this code and counts it against the score, serve prints one notice when a source flips, and gbrain sources writer movement judges a window after a restart and exits 1 with this code (reason: movement_check) when pending work does not move.
Run gbrain sources writer status --source --json (read-only): its next_action names the owner process, the step it is parked on and whether to wait or restart it. After the fix, gbrain sources writer movement proves the data moves again. Run: gbrain sources writer status --source '{source_id}' --json
host_admin
gbrain doctor --only managed_sync_not_moving --json
An automatic remediation run (gbrain onboard --auto, doctor --remediate, MCP run_onboard, autopilot) did not submit a manual-only step: the schema-pack upgrade (unify-types) or the paid takes bootstrap (extract-takes-from-pages).
A pack upgrade retypes pages and switches the brain's schema pack, and the takes bootstrap pays a model per page; both are the user's one-time decision, so only the user submits them. A job of that kind an earlier run already queued is listed in queued_jobs and still runs unless cancelled.
Show the user the step and its fix.command (gbrain jobs submit <job> --follow, with --params when the step has them); the user runs it after reviewing gbrain onboard --check. Cancel a listed queued job with gbrain jobs cancel <id> if the user does not want it. Run: gbrain jobs list --status waiting
user
repeat the read that failed
1
no
membership_inactive
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The shared-skills enrollment epoch was left or superseded.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
A memory writeback setting change did not confirm, so it may or may not have been saved.
A database write that throws can be a rollback or a lost acknowledgement, and the two look the same to the caller. The setting and its audit row commit together, so a re-read shows which happened.
Call get_memory_settings to read the mode in effect, and change it again only if the change did not land.
The content-repair model judged a held file and the page its frontmatter slug: names to be the same page, so gbrain recommends merging them instead of removing the slug line; nothing was written.
A frontmatter_slug_conflict hold whose two sides describe the same person, company or topic is a duplicate, and the deterministic repair (delete the slug: line) would mint a second page for it. gbrain does not merge pages by itself yet (a lossless merge needs a coordinated two-page write with both revisions, withdrawal and metadata preservation; it ships separately), so the lane records the recommendation on the hold as codes and slugs (meta.content_repair: the canonical slug that keeps the page), gbrain sync status renders a paragraph for a person, and nothing retries it until the file changes.
Show the user the paragraph gbrain sources status --json renders for the hold (the path, the canonical slug and the recommendation). After they agree, merge the unique sections of the duplicate into the canonical page, delete the duplicate file, commit, and run gbrain sync --source --no-pull; the hold clears on that sync. Run: gbrain sources status '{source_id}' --json
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
migration_declined
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
An explicit apply-migrations --migration named a migration the brain's config declines, so nothing was run or written.
The migration's opt-out key (for v0.53.0: shared_skills.migration.enabled=false) is brain-level config shared by every machine on that database; an explicit run from one machine would rewrite config for all of them, so the runner refuses instead of overriding the owner's choice. Ordinary runs skip a declined migration and list it as declined.
Do not retry. Tell the user the migration is declined on this brain and give them the fix command (gbrain config set true) if they want it to run; --list --json shows it declined.
user
repeat the read that failed
3
no
migration_failed
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A migration orchestrator failed, so the migration chain stopped; finished migrations stay recorded.
The server failed; this is not a caller mistake.
Server-side failure, not a caller mistake. Run gbrain doctor --json on the brain host; if it repeats, report it to the user.
Doctor warning: a migration stopped three or more runs in a row on a conflict in one or more sources and recorded that host work is still owed (today only v0.53.0).
Each source in conflict needs the user's decision. The migration's read-only preview names each source, its conflict code and the step that settles it, and doctor stops warning once the preview finds no source in conflict.
Run the read-only inspect gbrain apply-migrations --migration <version> --dry-run --json on the brain host to see each source's conflict, its code and its next step, and settle each one with the user. For shared_skills_unmanifested, declare the skills to share in a skillpack.json at the source's root, or keep the source out with gbrain sources shared-skills <id> off. Run: gbrain apply-migrations --list --json
A migration's mechanical checkpoint is recorded, but its stored report still names host work (for v0.53.0 a source's inventory, writer, projection or publication-policy stage, or a brain-level pending action); apply-migrations --list shows it applied_pending_host_work.
The ledger row is complete so the schema work never reruns, and v0.53.0 records apply_migrations_pending on every run because member enrollment is never verified, so the stored report decides (#6796): unenrolled members and sources that opted out are not host work. The next apply-migrations --yes re-check rewrites the report once the work is done.
Run the read-only inventory gbrain apply-migrations --migration <version> --dry-run --json on the brain host, do each source's next step it names (ask the user before publishing or activating), then run gbrain apply-migrations --yes. Run: gbrain apply-migrations --list --json
This apply-migrations run's own migration lease no longer matched its fence, so it stopped before the next migration.
The lease row still names this process (pid and host), but the fenced refresh matched no row: the direct and main database connections may reach different databases, or the row was rewritten. The details say whether the acquisition token and acquisition time still match (never the token itself). Run gbrain doctor --json and report it (#6028).
Server-side failure, not a caller mistake. Run gbrain doctor --json on the brain host; if it repeats, report it to the user.
host_admin
gbrain doctor --json
1
no
migrations_pending
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Schema migrations are behind (or could not be confirmed at head), or an orchestrator migration is wedged, so the command did not report success.
apply-migrations reasons: not_applied: the run had no --yes (or --non-interactive), so it did not apply the schema migrations; the fix applies them with --yes. still_behind: an authorized run tried them and they did not apply; another --yes repeats the failure, so run gbrain doctor --json and report; when a migration ran out of its statement budget (#7108) the error names it and its fix depends on the case: recorded by another release (rerun), an idle-in-transaction blocker (end it once the user agrees, rerun) or nothing blocking (once the user agrees, one run with --statement-timeout). schema_unreadable: the schema version could not be read back after the orchestrators ran, so the run cannot confirm it reached head; report it. wedged: an orchestrator migration ended partial three or more times in a row, so runs skip it until a person fixes the cause and clears it with --force-retry. Each failure names the migrations still pending. schema_behind (#6904): a managed write was refused at admission because the brain schema is below the version this build needs. Not retryable as is (class caller): the same write refuses until the migrations are applied; nothing was admitted, so the request_id was not consumed and the same request_id commits once the schema is migrated (a replay of an already accepted id still reconciles).
schema_behind: apply them with gbrain apply-migrations --yes as the database role that owns the gbrain tables (the brain host operator when this connection does not own them), then resubmit the write with the same request_id. not_applied: apply them with gbrain apply-migrations --yes. still_behind or schema_unreadable: run gbrain doctor --json and report it to the user; another --yes repeats the failure (a still_behind that names a timed-out migration carries its own fix: follow it). See docs/guides/troubleshooting.md#migration-statement-timeout. wedged: ask the user, read the migration's partial rows in the brain home's migrations/completed.jsonl (phases[].detail, if present; apply-migrations prints the resolved path), fix the cause, then gbrain apply-migrations --force-retry <version> and gbrain apply-migrations --yes.
Another apply-migrations run holds the migration orchestration lock.
A temporary condition (a lock, a pending write, a rate limit); the same request can succeed later.
Wait briefly, then retry the same request (writes: reuse the same request_id).
agent
repeat the read that failed
75
yes
missing_source_scope
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A remote tool call reached dispatch without a resolved source scope; the shared default source is refused.
The server failed; this is not a caller mistake.
Server-side failure, not a caller mistake. Run gbrain doctor --json on the brain host; if it repeats, report it to the user.
host_admin
gbrain doctor --json
1
no
missing_source_value
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A source flag was given without a value.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
models_strict_violation
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A configured model is not allowed under models strict mode.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
moved_pages_mass_fold_refused
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
gbrain repair moved-pages refused to fold moved pages amounting to more than half of a source's file-backed pages; nothing was changed.
The sync mass-delete valve (#2828) applied to moved pages (GST-2584): that many moved pages at once almost always means a re-import under other paths or the wrong checkout, not a backlog.
Check the source and its checkout first. If folding these pages is genuinely intended, ask the user, then rerun the same apply command with GBRAIN_ALLOW_MASS_RECONCILE=1.
gbrain sources writer movement could not read the managed sync backlog, so whether sync work is pending is unknown.
A failed backlog read is not an empty backlog: reading it as nothing_pending turned a stalled sync into an all-clear. The movement reader reports movement_state: unknown (unknown.reason: backlog_read_failed) on every surface, doctor warns, and the movement command exits 1 with this code instead of managed_sync_not_moving.
Rerun gbrain sources writer movement ; if the backlog read keeps failing, run gbrain doctor --json. Run: gbrain sources writer movement '{source_id}' --json
agent
gbrain doctor --only managed_sync_not_moving --json
The request itself was wrong or no longer matches the brain; nothing was changed.
Run gbrain init --pglite --no-embedding to create a local keyless brain (or gbrain init --help for hosted and Postgres options).
agent
repeat the read that failed
1
no
no_context_ceiling
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The model has a known price but no known context-token ceiling, so a user-set cost cap cannot bound one call; the job stopped before any provider call.
A user cap is enforced per provider attempt by reserving the most that attempt could cost: its input ceiling times the input price plus its output ceiling times the output price. Some providers (OpenRouter) declare no ceiling for their models, so the reservation has no bound even though the price is registered.
Do not retry unchanged and do not re-register the price. Ask the user whether to rerun without the user cap (the model then runs unmetered under the default cap), or to give the model's context size to the brain-host operator. Run: gbrain pricing list --json
The skill has no routing-eval rows to bootstrap a benchmark from.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
no_skill_md
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The skill directory has no SKILL.md.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
no_worker
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
No worker is running for this queue, so a queued job would wait until something runs it.
PGLite brains have no background worker (the database is single-writer), and a Postgres queue needs a running gbrain jobs work or supervisor. Queuing without one leaves the job waiting with no error.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
no_worker_surface
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
No worker surface.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
not_a_git_repo
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The source path must contain committed Git content.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
not_connected
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Google connect credential error: not connected.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
A managed sync pass used its rounds without the level settling (another writer kept changing it), so it ended resumable; everything it admitted stands.
A pass re-reads the level each round and stamps only when nothing is left to admit. Concurrent writes can keep producing new work; the next pass starts from what this one settled. Three in a row (the pass row's not_converged_streak) mean rerunning is not converging.
Rerun the same gbrain sync; after three consecutive not_converged passes, stop and report it with gbrain sync status --source --json and gbrain doctor --json.
The requested resource does not exist or is not visible to this caller.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
not_owner_host
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
This host does not own the source's active canonical worktree, so ghost pages (live pages whose canonical file is missing) cannot be checked or removed here; nothing was changed.
Whether a page's canonical file is missing is only known on the host that holds the source's checkout; another host would read its own disk.
Run gbrain repair ghost-pages --source in a terminal on the source's canonical owner host (writer status names it). Run: gbrain sources writer status --source '{source_id}' --json
The commit notifier kept a source due through every retry tier (5 s, 15 s, 1 min, 5 min) without the sync making progress; it keeps retrying every 5 minutes.
A commit-triggered sync failed or was refused the same way on every attempt, so the commit is still not searchable; the notifier block in gbrain sync status names the last error and the trace file with every attempt.
Run gbrain sync --source --no-pull in the foreground to see the error, fix its cause, then read gbrain sync status --source --json (the notifier block) to confirm the source is current.
A tool call carried on_behalf_of inside its arguments, where conversation text could set it, so it was refused and nothing was read.
Only harness code may name whose notes a shared agent reads: the X-Gbrain-On-Behalf-Of header or request-level _meta.on_behalf_of, never tool arguments.
Remove on_behalf_of from the tool arguments. Harness code sends it as the X-Gbrain-On-Behalf-Of header or request-level _meta.on_behalf_of; other stdio clients use a credential bound to one member or config mcp.stdio_member.
A shared agent's request named its audience (the X-Gbrain-On-Behalf-Of header or request-level _meta.on_behalf_of) in a form gbrain does not accept: empty, more than 50 entries, an entry that is not a member id, group: or guest, or a header and _meta that name different audiences. Nothing was read.
The audience decides whose notes the agent may read, so an audience gbrain cannot read exactly is refused instead of guessed.
Fix the harness code that sets the audience: 1-50 entries, each a member id, group: or guest, the same in the header and _meta when both are sent.
A shared agent asserted an audience its credential's may_act_for does not list (for a stdio server, config mcp.stdio_may_act_for), so nothing was read.
A shared agent acts only for the people the brain operator approved for its credential; widening that list is the operator's decision, never the agent's.
The brain operator decides whether to approve the audience: gbrain auth rescope --token |--client --may-act-for on the brain host. Until then, call without the audience.
A shared agent's audience names a member who is not enabled on this brain, or a group that does not exist, so nothing was read.
An unknown or disabled entry is refused rather than read as a guest, so a typo or a removed person never quietly changes what the agent reads.
Name enabled members and existing groups only (gbrain access member list --all, gbrain access group list on the brain host); a person who is not a member joins the audience as guest.
gbrain repair origin-twins refused to merge duplicate-origin twins amounting to more than half of a source's file-backed pages; nothing was changed.
The sync mass-delete valve (#2828) applied to origin twins (#6948): that many twins at once almost always means a re-import under other slugs or the wrong checkout, not a backlog.
Check the source and its checkout first. If merging these pages is genuinely intended, ask the user, then rerun the same apply command with GBRAIN_ALLOW_MASS_RECONCILE=1.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
owner_marker_missing
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The ownership marker (.gbrain-owner.json) is missing from a managed source's checkout root while the reservation beside the checkout still names this owner, so no write publishes there.
The marker binds the checkout directory to its owner. A cleanup or a restore that drops dotfiles removes it; a retry never brings it back, so a write refused with this code ends terminally and releases its outstanding-request slot. The verified self-transfer re-creates it for the same root on the owner host; creating or copying it by hand is refused.
On the brain host: gbrain sources writer status --source --json (note admin_state), then gbrain sources writer transfer prepare --self-transfer and transfer accept with the manifest it prints; then run the same gbrain sync again (a sync stops blocked_by_failures on the refused file, with no hold). Run: gbrain sources writer status --source '{source_id}' --json
The source's canonical owner cannot run this write or maintenance step right now; reason says which condition.
A managed source publishes only through the host that owns its checkout. host_mismatch: another host id owns it (two GBRAIN_HOME identity files on one machine look the same; both ids are printed, and a retry on this host cannot help). transfer_in_progress: the worktree is draining for a writer transfer, which ends when the successor accepts it or the owner host runs gbrain sources writer transfer cancel; a drain prepared over 30 minutes ago asks the user which (ask_user) instead of waiting. clone_in_progress: a topology clone is recovering it and clears by itself. binding_missing, incarnation_changed, local_path_missing and coordination_path_missing name an incomplete or outdated registration. not_sent / outcome_unknown: the local owner's IPC lane did not take the write, or lost its acknowledgment. detail: unbound_source: on Postgres the source has a checkout but no canonical owner, a configuration state rather than a transient one (not retryable); in classic mode the write path is the file, a commit and gbrain sync.
Read gbrain sources writer status --source --json on the brain host. A transfer or clone in progress: wait and retry. host_mismatch: run the step on the owner host, or give the worker and the shell one GBRAIN_HOME; never copy or regenerate host.json. Nothing claims or transfers ownership to run maintenance.
This large page's segment rows readable on this connection do not cover its body, so the read returned nothing rather than a short or empty body.
A segmented page keeps its body in manifest rows that must tile the stored body from its first byte to body_bytes; a role that sees the page row but not its manifest rows (a row-level security policy or grant that covers pages only), or rows missing from the database, would otherwise read as an empty or truncated page with nothing to say so.
Give the role that reads the brain the same access to page_body_manifest and page_segment_texts it has to pages (the brain host's operator), then read again; run gbrain doctor --json to check the segment tables. When doctor segmented_tiling lists the page, its rows are missing: preview gbrain repair segmented-tiling --source , which republishes it from Git.
This page's body is stored in segments, and the path that hit it reads or writes the whole body as one string, so it stopped before reading or changing anything.
With pages.segmented_storage on, a page over 1 MiB keeps its body in segments instead of the page row; a whole-body path would otherwise see an empty body and could overwrite the page or drop the unread rest. Windowed reads and segment-aware writers replace these paths.
Retrying refuses the same way. Read the page in pieces: get_page body: 'auto' returns its outline and first window, and body: 'window' reads any lines or bytes. Run: gbrain get --source '{source_id}' --body auto -- '{slug}'
A segment of this large page has projection metadata gbrain cannot use, so the read returned nothing for it rather than unsanitized text.
Windows of a segmented page are cut from each segment's stored protected regions; when they are stale (another segmenter version, a text that does not match its hash) gbrain recomputes them from the segment's carried parser state, and refuses when that state is missing or of another version, or when a facts fence block crosses a forced cut while the source has withdrawals.
Rewrite the page body (import or sync its file again), which segments it with this gbrain version, then read it again; other windows and the outline still work.
put_page refused to replace a large page with content much smaller than the stored body; nothing was written.
Above the inline read size (mcp.inline_body_bytes, 256 KB) a get_page read returns a window, not the body, so a replacement far smaller than the page is most often a window sent back as the whole page, which would delete the unread rest.
Change part of the page with edit_page (revision from get_page body: 'none'). Pass allow_shrink: true only when the smaller content is the intended complete page. Run: gbrain get --source '{source_id}' -- '{slug}'
The whole page does not fit one result on this connection, so get_page did not return its body.
A result is measured as the complete encoded frame; a body over the connection's cap (mcp.max_result_bytes_stdio, 4 MiB; mcp.max_result_bytes_http, 1 MiB) would be cut or rejected by the client. Nothing was truncated: windowed reads cover the whole page in pieces.
Read the outline (body: 'outline'), then windows (body: 'window' with lines, bytes, around_chunk_id or the returned next_cursor). To replace the page, edit it with edit_page and the revision from body: 'none'. Run: gbrain get --source '{source_id}' -- '{slug}'
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
parser_regression
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A file whose exact bytes imported before is now refused by gbrain's frontmatter reader.
The same bytes imported under an earlier gbrain version, so only gbrain changed; such a file is held and the rest of the sync continues (GBRAIN_SYNC_PARSER_REGRESSION=stop for the process that syncs stops the run instead).
Report it as a gbrain bug with the gbrain version, the file and the code; upgrade or pin the last good version, then sync again.
host_admin
gbrain doctor --json
1
no
part_splits_code_point
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
An upload part starts or ends inside a code point (half of a surrogate pair), so it was not stored.
Each part is stored as raw UTF-8 bytes; half of a surrogate pair has no UTF-8 encoding, so a part cut there would corrupt the character.
Move the cut before the high surrogate so the pair travels in one part, then send the part again.
agent
repeat the read that failed
1
no
part_too_large
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
An upload part's encoded frame is over the connection's part limit (part_max_frame_bytes), so it was not stored.
part_max_frame_bytes is the connection's inbound request cap (at most 4 MiB) minus a 4 KiB envelope; JSON escaping makes quotes, backslashes and control characters count more than once.
Cut the part so the whole call stays within part_max_frame_bytes, then send it again with the same part number.
agent
repeat the read that failed
1
no
pasted_wrong_url
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Google connect credential error: pasted wrong url.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
The --pat-file token file is missing, empty, holds more than one token, or is readable by other users, so it was not read.
The token is read from a private file so it never appears on a command line or in a process list; a file other users can read would leak it, so the verb refuses before any credential is written.
Write exactly one token on one line to a file, chmod 600 it, and pass its path with --pat-file.
agent
repeat the read that failed
1
no
path_not_utf8
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A committed file's name is not valid UTF-8, so managed sync holds that file alone.
Git hands the name back with U+FFFD for the bytes that are not UTF-8 (a Latin-1 name from an older system, an archive or a network share), and no Git read or file matches that decoded name, so nothing is imported from it. The rest of the source keeps syncing.
Rename the file to a UTF-8 name (git ls-files with core.quotePath shows its exact bytes; convmv -f latin1 -t utf8 converts a Latin-1 name), commit, then sync again; the rename clears the hold.
An existing pattern page is waiting on the rewrite that de-duplicates its claim sources, so no patterns child was submitted this run.
The patterns child reads existing pattern pages; until their claim records reference one shared reflection list, the pages can overflow the model's window and the run pays for nothing.
Wait briefly, then retry the same request (writes: reuse the same request_id). Run: gbrain write-requests --source '{source_id}'
agent
repeat the read that failed
1
yes
patterns_min_interval
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
An in-cycle dream patterns run was skipped because the partition's last completed patterns run ended less than dream.patterns.min_interval_hours ago; nothing was submitted.
Every maintenance pass writes new reflections, so the evidence watermark alone re-ran a paid patterns child on each pass. The skip names next_eligible_at; a direct gbrain dream --phase patterns or --once is not held to the interval, and gbrain config set dream.patterns.min_interval_hours 0 turns it off.
Wait for next_eligible_at, or, with the user's paid authorization, run gbrain dream --phase patterns now. Run: gbrain dream --phase patterns
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
pending_import_expired
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A write that waited for managed sync to import a committed change to its page's file was not applied, because the import had not landed after the barrier's wait limit.
With persistence.refresh_barrier on, a put_page, capture, remember or add_timeline_entry whose page file holds a change committed through Git that managed sync has not imported yet is accepted and waits for that import instead of being refused pending_import. An import that never lands (no sync owner running, a sync stopped on the file) would hold the write forever, so the owner finishes it failed once one hold has lasted persistence.refresh_barrier_max_wait_ms (15 minutes by default), or once it has waited four of those limits (at least 4 hours) since its admission across repeated holds. Nothing was applied. A remember ends as its pending_import refusal did instead: one that named its entity is replayed by the first sync that imports the file, and gbrain repair failed-writes lists the rest for a person to replay.
Check the source with gbrain sync status --source --json, then read the page again and submit the write with a new request_id.
gbrain bootstrap harness --token wired the harness on a PGLite brain while no gbrain serve answered, so the wiring is not verified yet; nothing failed.
On PGLite the serve holds the single-writer lock, so a stopped serve is the normal state for wiring; the smoke test needs the serve, so it waits for the re-run.
Start gbrain serve --http for this brain, then re-run the same gbrain bootstrap harness command with the same --token; gbrain bootstrap harness --status stays partial until that run passes its smoke test.
A pending source write prevents verified completion.
A temporary condition (a lock, a pending write, a rate limit); the same request can succeed later.
Wait briefly, then retry the same request (writes: reuse the same request_id).
agent
repeat the read that failed
1
yes
permission_denied
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
This caller is not authorized for the operation.
Only the operator of the brain host can change what blocks this.
Only the brain host's operator can resolve this. Tell the user the message and run gbrain doctor --json on the brain host.
host_admin
gbrain doctor --json
1
no
persistence_restart_required
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
This gbrain serve's persistence consumer reports restart_required, so it claims no write until the process restarts; /health?deep=1 answers 503 with this code.
A preparation abandoned past the ceiling (a zombie) or a publication that never settled past its deadline makes the owner stop claiming on every root, because the abandoned work may still hold locks or write files; only a process exit releases it. The deep health probe reports it so a supervisor can restart serve; it never acts on its own (GBRAIN_SERVE_RESTART_REQUIRED_EXIT_SECONDS opts into an exit).
Restart the serve process (for the installed service: systemctl --user restart gbrain-serve; otherwise stop and start it in the foreground); to let a supervisor do it unattended, set GBRAIN_SERVE_RESTART_REQUIRED_EXIT_SECONDS=300 in the serve environment (~/.gbrain/env for the installed service). Then run gbrain sources writer status --json.
A managed write request has held its claim longer than persistence.max_claim_ms, so later writes on its root wait behind it.
The owner renews a claim for as long as its work is unsettled, so a preparation or publication that hangs never lets the lease lapse; doctor names the stuck phase, the root, the claim's age and whether the same request resumes on its own.
Inspect the request with the command in fix, then restart the gbrain serve that owns the root; attach that status output when reporting the hang. Run: gbrain sources writer status --source '{source_id}' --json
A Postgres connection the driver retired after an incident (stuck, desynced, or closed under running statements) could not reconnect; statements waiting for it failed with the connect error.
The database or pooler refused or dropped the new connection (unreachable host, exhausted connection slots, rotated credentials). The next statement retries the connect, and the connection stays marked until one succeeds, so a repeating line means the pool is not recovering on its own.
Check the database and pooler from the serve host (gbrain doctor --only pool_reap_health --json); a serve that keeps logging this line needs the database reachable again, then a restart if the pool never recovers. Run: gbrain doctor --only pool_reap_health --json
A pooled Postgres statement ran past its in-flight budget (the pool's statement_timeout plus grace, or the longer statement_timeout its operation declared) with nothing coming back from the server (reason=idle) or while bytes kept arriving (reason=age), so the driver retired that connection; the statement and everything queued behind it failed with CONNECTION_STUCK.
Nothing arriving for that long usually means the connection is wedged: a pipeline the server and client no longer agree on, a transaction-mode pooler that swallowed a CancelRequest and left the backend in ClientRead, or a dead peer. It is not proof: behind a transaction-mode pooler the startup statement_timeout never applies (SHOW statement_timeout reads 0), so a legitimately slow statement can reach the budget too. reason=age is a statement that kept streaming rows or notices past its budget (#6543); an operation that needs longer declares it with SET LOCAL statement_timeout (0 for no limit), which the driver tracks per statement. Before #6383 such a connection held its queue forever while /health answered 200. The pool reconnects on its own; the warn line names the pool, the age, the queue depth and the statement by keyword and table.
Retry the failed call. If the line repeats, run gbrain doctor --json and report the warn lines with the operations that preceded them; GBRAIN_PG_STUCK_GRACE_MS raises the grace, and off disables the watchdog. Run: gbrain doctor --json
The Postgres pool of a resident gbrain process has had connections checked out or statements waiting for one across two 30 s ticks without completing a single statement.
One slow statement is one quiet tick; two in a row with nothing settled means every checked-out connection is waiting on the server at once, which is what a wedged pool or an unreachable database looks like from inside the process. With the in-flight watchdog on, the stall ends within statement_timeout plus grace and a pg_pool_recovered line follows; with it off this line is the only trace.
Wait one more tick for pg_pool_recovered or pg_connection_stuck; if the line keeps repeating, check the database and pooler (gbrain doctor --json) and restart the process if the pool never recovers. Run: gbrain doctor --json
A Postgres statement could not be built from its parameters (UNDEFINED_VALUE: a parameter was undefined; MAX_PARAMETERS_EXCEEDED: more than 65534 parameters) and was answered in its place in the pipeline by a query the server refuses; it failed, and a transaction it was part of was aborted rather than committed without it.
Either a gbrain programming error at the call site the warn line names by keyword and table (and by param=$n), or, behind a transaction-mode pooler (port 6543, prepare off), a value read from a row that belonged to another statement: a pooler that misroutes pipelined answers hands a statement someone else's row, and binding one of its missing columns fails here. Before #6383 the same failure, when it happened behind another statement on the connection, rejected that other statement, desynced the connection and left every later statement on it hanging; the driver now answers the culprit in its place (the approach of porsager/postgres#1236), so only it rejects and a transaction it was in aborts.
On a transaction-mode pooler, check /health?deep=1 transport (max_pipeline should be 0; PGMAX_PIPELINE=0 on the serve environment forces it) and treat earlier reads as suspect (docs/guides/pooler-misroute-audit.md); otherwise report the warn line (it names the statement and parameter) as a gbrain bug so the call site gets a null where it bound undefined.
Another gbrain process holds this PGLite brain's single-writer lock.
A temporary condition (a lock, a pending write, a rate limit); the same request can succeed later.
Wait for the current command or server to close, then retry. Do not remove a live lock. Reason legacy_owner_unverified is different: a lock folder from an older release whose owner cannot be proven dead never frees itself, so ask the user and run the read-only preview in fix (gbrain pglite-repair --legacy-lock --dry-run).
A PGLite vector (HNSW) index build was refused before it started because its in-memory graph would not fit PGLite's WebAssembly heap.
pglite.wasm caps memory at 2 GiB and pgvector keeps the whole HNSW graph in memory while it builds; a build past the budget used to run out of memory or fall back to hours of on-disk inserts. Vector search keeps working with exact scans.
Preview a move to Postgres (read-only): gbrain migrate --to postgres --plan --json Run: gbrain migrate --to postgres --plan --json
Server-side failure, not a caller mistake. Run gbrain doctor --json on the brain host; if it repeats, report it to the user.
host_admin
gbrain doctor --json
1
no
plan_stale
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The saved plan has no valid repository identity.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
pool_inflight_over_budget
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A pooled statement of this gbrain serve has run longer than its in-flight budget (the read pool's statement_timeout plus grace, or the longer statement_timeout its operation declared); /health?deep=1 answers 503 with this code.
Since #6543 the in-flight watchdog retires a statement past its budget whether or not bytes keep arriving (reason=age), so this code means the watchdog is off (GBRAIN_PG_STUCK_GRACE_MS=off), the serve runs a driver without per-statement budgets, or the retirement is still in progress; a transaction that declared a longer statement_timeout, or an index build that declared 0, is measured against its own budget and not reported. Through a transaction-mode pooler a pipelined answer can also be misrouted. The probe reports it and never retires the connection, because the endpoint is unauthenticated.
Restart this gbrain serve. On a transaction-mode pooler check the transport block of /health?deep=1: max_pipeline should read 0 (set PGMAX_PIPELINE=0 in the serve environment to force it) and session_timeouts_not_applied names the ALTER ROLE fix. GBRAIN_SERVE_RESTART_REQUIRED_EXIT_SECONDS does not act on this code: restart serve yourself or from your health check.
TLS was required by default for a non-local Postgres host, and the server does not accept TLS connections, so gbrain did not connect.
gbrain connects with sslmode=require to any Postgres host that is not on this machine (localhost, 127.0.0.0/8, ::1 or a Unix socket) unless the database URL names an sslmode, so the password and page contents never cross a network in plaintext without an explicit choice. Brains whose URL had no sslmode connected in plaintext before this default.
Turn TLS on at the database server and keep the default (sslmode=require encrypts; sslmode=verify-full with the server CA also verifies the certificate). To keep connecting without TLS on a network you trust, add sslmode=disable to the database URL. Run: gbrain engine status --probe --json
user
gbrain doctor --only postgres_tls --json
1
no
preparation_stalled
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A managed write's preparation was cut off at its deadline persistence.max_preparation_attempts times (default 2), so the owner finished it failed instead of claiming it again.
One request whose preparation never finished used to hold its root for as long as its owner renewed the claim; now each attempt has a budget, a cut-off attempt is counted (a kill mid-preparation included), and at the limit the request is terminal so the rest of the root keeps moving. A sync holds that file with the same code; the receipt names the last recorded step and what it was waiting on.
Inspect the owner with gbrain sources writer status --source --json (the step and its wait cause), fix or report the cause, then gbrain sources retry-held and the same gbrain sync with the same options; a foreground write needs a new request_id. Run: gbrain sources status '{source_id}' --json
A temporary condition (a lock, a pending write, a rate limit); the same request can succeed later.
Wait briefly, then retry the same request (writes: reuse the same request_id).
agent
repeat the read that failed
1
yes
proposal_closed
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The memory proposal is no longer awaiting the owner (approved, denied, expired, cancelled, failed or in conflict), so it was not approved or denied again.
A proposal is decided once; the decision and the receipt it left stay as they are.
Read how it ended with gbrain memory-proposals show ; the proposer sends a new proposal if the change is still wanted.
Too many memory proposals already await the owner for this person (proposals.max_pending_per_actor) or this credential (proposals.max_pending_per_credential), so this one was not saved.
The caps keep one system credential from flooding the owner with held text.
Wait for the owner to decide or for a proposal to expire, or cancel one with cancel_write_request; the operator sets the caps.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
provider_response_unparseable
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A model provider answered with a success status, but its response body could not be parsed as one JSON document; no response text is kept.
The same request gets the same body, so retrying spends another paid call on the same failure. The common cause is a provider route that streams (Server-Sent Events) when a request omits stream; a job that hits it ends on its first attempt.
Ask the operator to make the route return one JSON body for a non-streaming request, for example with gbrain config set provider_chat_options.: '{"stream": false}', then retry the job.
host_admin
gbrain doctor --json
1
no
publication_pending
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The catalog adoption is accepted but not fully committed.
A temporary condition (a lock, a pending write, a rate limit); the same request can succeed later.
Wait briefly, then retry the same request (writes: reuse the same request_id).
agent
repeat the read that failed
1
yes
publish_scan_unreadable
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
An automatic publish could not read its local commits in full to scan them for secrets (a missing or corrupt object, git output the scan does not recognise, or the 300 s budget); no secret was reported and nothing was pushed.
Only the operator of the brain host can change what blocks this.
Only the brain host's operator can resolve this. Tell the user the message and run gbrain doctor --json on the brain host.
A gbrain-owned clone (sources add --url) has local changes in its checkout, so git pull --ff-only cannot fast-forward it and every sync of the source stops at the pull.
Older gbrain releases appended ## Facts fence rows to clone files on unmanaged brains (#6946); a local change to a file the upstream also changed blocks every fast-forward. Current releases keep facts about a clone database-only.
Ask the user, then preview the repair: gbrain repair url-clone-fences --source . It proves which files differ from HEAD only by gbrain fence rows and restores those after keeping their facts database-only; a file with any other edit is named and left for the user.
A page purge's in-transaction journal lookup hit the publication transaction's statement budget, so the purge failed terminally; nothing was removed, tombstoned or redacted, and later writes to the source move again.
The lookup is deterministic on a large request table, not contention: retrying it as database_contention requeued the same purge forever and held every later write to its source behind it. The substring search for the page's claims now runs at preparation under the preparation budget; this code is for the lookups that still run inside the transaction (the slug lookup, the tail and pending re-checks, the locking read).
Do not assume the requested content was erased. If the receipt names the slug index as missing or INVALID, run gbrain repair request-indexes --apply first; then submit the purge again with a new request_id (a retry with the same id returns this failure). Run: gbrain repair request-indexes --json
A purge could not append its intent line to the purge mirror (/.gbrain/purge-events.jsonl), so it was refused; nothing was removed, tombstoned or redacted.
Restore replays the purges recorded in that text-free mirror; a purge that committed without its line would come back silently from an older backup.
Do not assume the requested content was erased. Make the mirror a writable regular file owned by the brain's user (mode 0600), then run the purge again with a new request_id.
A restore stopped because the replay of a purge could not sweep every stored request that carries the purged page; that purge was not replayed and nothing was restored.
A replayed purge removes what the live purge removed, the request journal included; reporting a partial sweep as replayed would leave purged text in the restored brain.
Do not use the restored copy. Report the purge request named in the message with the output of gbrain doctor --json; restore again once it is fixed.
The content matches a purged fact, take or page in this source, so it was not saved.
A purge leaves a text-free tombstone (the claim fingerprint or the page content hash) so stale files, re-syncs, reverts and re-extraction cannot bring purged content back.
Do not retry the same content. Write it in new words if it is still true, or ask the user to clear the tombstone on the brain host (gbrain pages purges list, then gbrain pages unpurge for a page).
The Git host refused the push for the credential git used ("Repository not found", HTTP 404, or HTTP 403); the commit is durable locally and nothing was pushed or retried.
A host answers "Repository not found" to an account that cannot see a private repository, and 403 to one that may not write to it. The same credential is refused on every attempt, so a retry only hides the fault while commits stay on this machine; which credential git uses is the user's configuration, and gbrain never changes it.
Relay the message to the user: it names the credential helpers git asked (with the scope and file that configure each), which one answered and its account login. Once they make git use a credential for an account that can push there, run gbrain git commit-push --push-only.
Pinned questions are owner-private: this connection cannot read private pages (or is slug-fenced or delegated), so the owner runs the command on the brain host.
Only the operator of the brain host can change what blocks this.
Only the brain host's operator can resolve this. Tell the user the message and run gbrain doctor --json on the brain host.
The bounded queue is full; existing requests keep their place.
A temporary condition (a lock, a pending write, a rate limit); the same request can succeed later.
Wait briefly, then retry the same request (writes: reuse the same request_id).
agent
repeat the read that failed
1
yes
rank_entities_timeout
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
rank_entities did not finish within its statement deadline (Postgres statement_timeout); nothing was ranked.
The ranking aggregates every edge in scope in one statement; a whole-brain ranking on a large graph can exceed the deadline, and a partial ranking would misstate the top rows.
Narrow the ranking with source_id, types or link_type, then call rank_entities again.
The request was rate-limited; retry after the stated delay.
A temporary condition (a lock, a pending write, a rate limit); the same request can succeed later.
Wait briefly, then retry the same request (writes: reuse the same request_id).
agent
repeat the read that failed
1
yes
read_budget_exhausted
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A subagent's get_page result came back as a short summary because the job has used its read budget (for the dream patterns child, dream.patterns.child_read_budget_kb).
A CLI-backed model replays the whole transcript on every turn, so a child that read every page in full filled the model window. The summary keeps the slug, title, type and a short excerpt; writes still work.
Work from the pages already read and append with add_timeline_entry instead of rewriting a summarized page. An operator who needs more reads raises dream.patterns.child_read_budget_kb (0 turns the budget off).
A remote write's readable_by is malformed, removes the field from a page that names readers, or would leave the page unreadable by the writer; nothing was written.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
A fact purge stopped before deleting anything: the source's Git history has more commits than the purge reads (200,000) when it looks for change reasons quoting the claim.
Purge tombstones every commit whose gbrain-reason trailer quotes the claim, so no later sync or re-import stores that reason again. Past the limit it cannot say which older commits do, so the user decides.
Ask the user: purge now and check only the newest commits (--reason-scan-limit , their choice; older commits are not tombstoned), or stop.
A sync imported its files but did not read their change reasons from Git: the range held more than 10,000 commits. Each reason in the pass is stored as empty and each page it changed is marked with a history gap.
Reasons are metadata, so content import never waits on them. The pass still advances last_commit and this release does not backfill reasons for that range; they stay in Git.
Nothing to repair. The reasons for the range are in Git: git log --first-parent shows them.
A sync imported its files but could not read their change reasons from Git (a Git error or a timeout). Each reason in the pass is stored as empty and each page it changed is marked with a history gap.
Reasons are metadata, so content import never waits on them. The pass still advances last_commit and this release does not backfill reasons for that range; they stay in Git.
Nothing to repair. The reasons for the range are in Git: git log --first-parent shows them.
A gbrain-reason trailer already pushed to Git looks like it holds a secret; sync stored no reason for that commit and path.
A secret in a reason is refused at write time; a commit made outside gbrain can still carry one. Git history keeps commit messages, so the credential stays exposed until it is rotated.
Rotate the credential the notice names (by commit and path); the brain stores nothing of it.
A remote caller's managed sync admitted what it could, and the rest of the source needs the owner host (holds, markers, keep_db writes or the stamp).
Remote callers admit only one-sided work and never write holds, markers, keep_db writes or stamps (design v3.2 §5), so only the owner host's sync converges the source.
On the host that owns the source, run gbrain sync --source --no-pull; verify with gbrain sync status --source --json.
A Git listing the managed-sync reconcile reads (ls-tree, ls-files, diff-tree) did not finish cleanly: Git exited non-zero, was killed by a signal or its time or size cap, or its output did not end at a record boundary.
A partial listing would make files look deleted or new, so the level is refused rather than classified. In PR 4a only the read-only convergence shadow reads it, and it reports status: unavailable with this code.
Check the checkout with git -C status, then rerun the read-only status; report it with gbrain doctor --json if it repeats. Run: gbrain sync status --source '{source_id}' --detail --json
gbrain repair stuck-recovery cannot apply that --keep choice to a page recovery over the single-string ceiling, because the staged copy of its prior file is missing, does not match its recorded SHA-256, or is not a regular file; nothing was changed.
A prior file over 24 MiB is not embedded in its recovery record: the record names a staged copy beside the file by path and SHA-256, and only that copy can put the prior bytes back. Without it --keep prior has nothing safe to restore, so the remaining exit is --keep disk, which the user must agree to.
Stop and ask the user; re-run only with the authorization the message names.
An earlier write left state that must be inspected and recovered before new writes.
Details name the exit when there is one: physical_root_device_changed (the checkout's filesystem device number changed; re-stamped by itself when ownership verifies) and physical_root_directory_changed (the directory at the recorded path was recreated, or its birth time drifted beyond 1 µs; the relocated-root self-transfer, transfer prepare/accept <source> --self-transfer --confirm-relocated-root, re-stamps it) and physical_root_moved (the checkout was moved to a new path or its parent folder renamed; sources add, set-path and writer claim, dry runs included, name the recorded path and the symlink-then-set-path or move-back exit, and a remote caller sees no path). All three are explained in docs/guides/write-refusals.md.
Only the brain host's operator can resolve this. Tell the user the message and run gbrain doctor --json on the brain host.
host_admin
gbrain doctor --json
1
no
recovery_version_unsupported
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A newer gbrain wrote this recovery record (its version is unknown here), so this gbrain left the record, its staged files and the canonical file untouched; writes on that worktree wait for it.
A recovery record says how to finish an interrupted publication; reading a newer layout as an older one can publish wrong bytes, delete a staged file or clear the record. Only a gbrain that knows the version may recover it, so the fix is upgrading gbrain on the canonical owner host and restarting its writer processes.
Only the brain host's operator can resolve this. Tell the user the message and run gbrain doctor --json on the brain host.
A write that waited behind a worktree refresh was not applied, because the refresh was still unfinished after the barrier's wait limit.
With persistence.refresh_barrier on, a page write that reaches a refreshing checkout is accepted and waits for the refresh to end. A refresh that never ends (a stuck member sync, a host that stopped) would hold those writes forever, so the owner finishes each one failed after persistence.refresh_barrier_max_wait_ms (15 minutes by default). Nothing was applied.
Check the refresh with gbrain sources writer status --source --json, then submit the write again with a new request_id.
A GitHub push arrived for a managed source: a managed source never pulls, so the pushed commit is recorded as wanted and waits for a refresh.
Managed sync imports the checkout's own HEAD; remote commits come in through gbrain sources refresh, which updates the worktree under the writer lock. The push's commit is kept as a wanted marker until the source reaches it.
Run gbrain sources refresh on the brain host, then gbrain sync --source --no-pull (a resident notifier runs the sync on its own).
A renamed file is held because the page it was renamed from changed after the rename was recorded.
Moving the page now could carry the newer edit to the wrong file, so the rename waits for an explicit re-bind.
Preview the frontmatter repair with --include-ambiguous to re-bind the rename to the current page, and approve it.
agent
repeat the read that failed
1
no
Reasons: rename_source_changed.
rename_identity_unreadable
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A renamed file is held because the database refused to compare its title or frontmatter id (SQLSTATE 22021/22P05), so sync could not tell whether it is the page it replaces.
Which page a file is cannot be decided without comparing its identity; the old page keeps its id, links, facts and timeline and the rest of the source keeps syncing.
Remove the NUL byte or broken Unicode character from the file title and id, commit, and sync again; the pair is decided again when the file changes.
agent
repeat the read that failed
1
no
rename_reconcile_failed
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A renamed file imported, but removing the page of its old name failed unexpectedly, so that page was kept and may be a duplicate.
An unexpected error is deterministic, so a blocking marker would stop the source on every run; the rename is held instead and the rest of the source keeps syncing.
Ask the user before a full sync of the source (gbrain sync --source --full --no-pull), which removes pages whose file is gone, or remove the old page with gbrain delete.
agent
repeat the read that failed
1
no
repair_preview_timeout
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A gbrain repair failed-writes preview read ran past the database statement timeout, so the preview stopped; nothing was saved, no approval checkpoint was written and no page changed.
The preview classes every refused caller write against the write journal (replay attempts, later requests of the same page, recovered fact requests) in a few set reads. They use the persistence_requests_replay_id and persistence_requests_slug_sequence indexes; when either is missing or INVALID, or the journal is large enough that a set read outlasts the timeout, the server ends the read.
Build the request indexes with gbrain repair request-indexes --apply, then run the same preview again; if it stops again with the indexes valid, run it once with a longer statement timeout on the brain host. Run: gbrain repair request-indexes --json
This optimizer publication request has already been submitted.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
request_too_large
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The request exceeds a configured capacity; narrow it.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
requester_scope_required
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A remote read came from a connection bound to no member (an access token, an OAuth client or a local stdio server) on a brain that serves several people (two or more enabled members, or config access.serves = several), so it was refused before any work and nothing was read.
On a brain that serves several people a connection bound to nobody reads every page no rule restricts, for whoever is asking; gbrain refuses rather than guess whose notes a read is for. A connection that existed when the brain started serving several people gets 14 days of in-band notices first (reason grace_ended); one created after that is refused at once (created_after).
On the brain host, bind the connection to the person it serves: gbrain auth rescope --token |--client --member (preview with gbrain access check --token ); for a stdio server, when only one person uses that harness, gbrain setup claude-code --stdio-member (gbrain setup codex --stdio-member on Codex), which binds that one harness entry on that machine (refused where OpenClaw or Hermes is installed); for a harness several people talk to, give each person a key over HTTP instead (gbrain serve --http with gbrain auth create --member keys). A shared agent lists whom it may act for (--may-act-for) and names the person on each call. Last resort: --reads-unscoped --yes lets that one credential read every page no rule restricts for any asker.
A remote read came from a connection bound to no member, and the brain's settings (whether it serves one person or several) could not be read: the config read failed, and so did one re-read. The call was not answered and nothing was read; this is not an access decision, and the same call can succeed once the database answers.
A statement timeout, a lock wait or a dropped pooled connection can fail one config read while the next read succeeds. Reading that as a one-person brain would let a connection bound to nobody read every page no rule restricts on a brain that may serve several people, so gbrain refuses until it can tell.
Retry the same call in a few seconds. If it keeps failing, the brain host's operator checks the database with gbrain doctor --json. A connection bound to a member is never refused this way.
The runtime requirements exceed the owner-approved publication policy.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
requires_local_engine
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
This command needs the brain's local database, and this install is a thin client of a remote brain.
Only the operator of the brain host can change what blocks this.
Only the brain host's operator can resolve this. Tell the user the message and run gbrain doctor --json on the brain host.
host_admin
gbrain doctor --json
1
no
reserved_frontmatter_key
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A remote page write tried to add or change a frontmatter key only a trusted derived writer sets (retired_by, retired_at, retired_generation); nothing was written.
Those keys mark a page a derived writer retired, which the purge holds for 30 days and the repairs treat as machine-owned. A remote caller that could set them could make a page look machine-retired. Carrying the stored value unchanged, or dropping the key, is allowed.
Remove the key from the frontmatter (or keep the stored value) and write the page again.
agent
repeat the read that failed
1
no
reset_upstream_refused
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
gbrain sources reset-upstream changed nothing: the checkout moved since the reset was proposed, has no upstream, has uncommitted tracked edits, or has local commits that were never on the upstream (named, with the backup ref a reset would create).
The reset is bound to the HEAD and upstream the user agreed to and drops only commits the upstream once had; anything else needs the user's decision first.
Correct the request using the message above, then retry.
Persistence response exceeds the local transport limit.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
restart_refused
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
gbrain upgrade (or --restart-only) found a gbrain process on this host it cannot restart onto the new build (a serve or worker started by hand, an autopilot started outside its service by a launcher gbrain does not know, a running sync, or an MCP server an agent harness started), so it restarted nothing and, before a swap, installed nothing.
A process keeps the build it started with, so restarting only some of them leaves serve, workers and MCP servers on different builds; the upgrade refuses instead of leaving that skew. Each process is named with the exact step that restarts it.
Handle each listed process as the message says (MCP servers only: rerun with --stop-mcp after the user agrees), then run the same command again; gbrain upgrade --no-restart installs without restarting. Run: gbrain upgrade --restart-only --dry-run --json
After gbrain upgrade restarted this host's gbrain processes, one of them still runs another build, did not come back, or the warm CLI socket refused the new build.
The restart is done only when every gbrain process on the host reports the installed build and serve's warm CLI socket accepts it; anything less is the version skew the restart exists to remove.
Restart each process the message lists with the command the plan printed, then run gbrain upgrade --restart-only again. Run: gbrain upgrade --restart-only --dry-run --json
The tool's result is larger than this connection can carry in one response, so it was replaced by this error; nothing was cut.
Results are measured as the complete encoded JSON-RPC frame (every block, notice and escape). A frame over the connection's cap (mcp.max_result_bytes_stdio, 4 MiB; mcp.max_result_bytes_http, 1 MiB) would be rejected or silently cut by the client.
Ask for less in one call: a window (get_page body: 'window'), a page of rows (limit / from_index), or metadata only (get_versions include_body: false). Run: gbrain get --source '{source_id}' -- '{slug}'
The page changed since the cursor or chunk id was issued, so that position no longer names the same text.
Cursors and chunk positions are bound to one page revision; reading on from them after an edit could skip or repeat text without saying so.
Read again from the position in fix (the same byte offset at the current revision), or start over with body: 'outline'. Run: gbrain get --source '{source_id}' -- '{slug}'
The target changed since it was read; the expected revision no longer matches.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry. Run: gbrain get --include-content --source '{source_id}' -- '{slug}'
agent
repeat the read that failed
1
no
revision_required
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The target already exists and the write named no revision: supply the expected revision read from the page (or the policy epoch) before replacing it.
Without the revision the write cannot tell an intentional replacement from an overwrite of an edit it never saw; nothing was changed.
Correct the request using the message above, then retry. Run: gbrain get --include-content --source '{source_id}' -- '{slug}'
agent
repeat the read that failed
1
no
revision_unavailable
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The exact authorized revision is unavailable.
A capability this request needs is not configured or not reachable on this brain.
A required capability is not available on this brain. Run gbrain doctor --json to see what is missing.
agent
gbrain doctor --json
1
no
runtime_build_skew
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Long-running gbrain processes on this host run different builds, or one runs an older build than its install holds on disk: serve, the jobs supervisor, worker parents (in memory) and the job children they spawn from the install (on disk).
A process keeps the code it loaded at start, and gbrain jobs run-child spawns a fresh process from the install on disk for every job, so after a checkout reset or an upgrade on disk newer job code runs under an older worker and next to an older serve until each process restarts.
Restart the process the check names (serve with its service command, the supervisor with gbrain jobs supervisor stop then gbrain jobs supervisor start --detach, a worker by stopping its pid so its supervisor respawns it), then each other listed process on an older build; nothing restarts automatically. Run: gbrain doctor --only runtime_build_skew --json
The Rust engine addon on this machine does not match what this gbrain release expects (checksum, engine_abi, engine_build or target), so it was not used and gbrain wrote nothing.
A different addon build could read or write the brain with a different on-disk format, so only the addon the running release names, with the checksum in its manifest, is loaded. A file that fails the check is left as it was.
Rebuild the addon with bun run rust:build and point GBRAIN_RUST_ENGINE_ADDON at the path it prints, or install the gbrain release that matches the addon, or switch engine in the gbrain config back to pglite or postgres.
The Rust engine is selected (engine: rust), but no addon for this gbrain release is installed on this machine, or no addon is published for this platform, so gbrain opened nothing and wrote nothing.
The Rust engine ships as a separate addon file kept in the gbrain home, checked against the checksum in this release's manifest before it loads. Without a checked addon the engine cannot open, and gbrain refuses before touching the brain.
Point GBRAIN_RUST_ENGINE_ADDON at an addon you built with bun run rust:build, or switch engine in the gbrain config back to pglite or postgres.
gbrain maintain --schedule wrote its files, but the operating-system scheduler (launchctl, systemctl --user or crontab) refused the job.
The scheduler belongs to the host: a missing user session bus, a locked crontab or a launchd error stops the job from loading.
Read the scheduler error in the message, fix it on the host, then run gbrain maintain --schedule --yes again (gbrain maintain --unschedule removes the files).
user
gbrain doctor --json
1
no
schedule_unsupported
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
gbrain maintain --schedule installed nothing: on Windows and in containers it has no installer, and it schedules the host brain only.
Windows gets the schtasks line to add by hand (minimal Windows support). In a container an operating-system schedule does not survive a redeploy, so the resident gbrain serve is the upkeep runner there. The scheduled job runs without --brain, so a mounted brain gets no schedule.
On Windows, add the printed schtasks line yourself. In a container, keep gbrain serve running; it runs free upkeep while idle. For a mounted brain, schedule gbrain --brain maintain --unattended yourself.
agent
repeat the read that failed
1
no
Reasons: windows, container, mount.
schema_lock_blocked
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A schema step (the schema.sql replay in init/upgrade, or one migration) waited its lock_timeout for a table lock another session holds and stopped instead of hanging.
Every ALTER TABLE in the replay takes an ACCESS EXCLUSIVE lock even as a no-op, so one open transaction in another client (idle in transaction, a stuck job) blocked gbrain init and upgrade forever with no output. The wait is now bounded (GBRAIN_SCHEMA_LOCK_TIMEOUT_SECONDS, default 60) and the refusal names the blocking sessions by pid, application and state, sampled while the wait was active; query text is never shown. The cancelled step changed nothing.
Let the named session finish or, with the user's agreement, end it on the database host with SELECT pg_terminate_backend(), then rerun the same gbrain command; init retries a few times on its own with a short backoff. Run: gbrain doctor --json
A pack mutation refused to write because the YAML it emitted did not read back as the manifest it holds; the pack file on disk is unchanged.
The write boundary parses its own output and compares it to the manifest as normalized structures, so an emitter/parser asymmetry can no longer corrupt a pack silently.
Re-run the mutation on the current release; if it refuses again, run gbrain schema validate <pack> and report the named key with gbrain doctor --json. Run: gbrain schema active --json
The schema pack file is larger than the load bound, so it was not read; a pack this large is almost always a quoted scalar (a link-type regex) whose backslashes an older release doubled on every mutation.
Loading a pack of that size took every CLI process to tens of GB of memory. The original text cannot be recovered automatically: after N doublings only the author knows the intended regex, so the fix is a hand edit of the grown lines.
Open the pack file named in the message, restore the grown quoted lines (usually inference.regex under link_types) to their intended text, save, and re-run. GBRAIN_SCHEMA_PACK_MAX_BYTES raises the bound for one command when a pack is legitimately large. Run: gbrain schema active --json
An agent-facing caller asked takes_scorecard for group_by or min_n, which read the private forecast journal and run only from the trusted local CLI.
The request itself was wrong or no longer matches the brain; nothing was changed.
Omit group_by and min_n; the brain owner runs gbrain takes scorecard --group-by on the brain host.
agent
repeat the read that failed
1
no
search_cursor_requires_keyword
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A search cursor was sent without match: "keyword"; cursors continue keyword listings only (hybrid rows are a ranked top-K with no next page).
The request itself was wrong or no longer matches the brain; nothing was changed.
Send the next object from the previous search response unchanged; it carries match: "keyword".
agent
repeat the read that failed
1
no
search_mode_local_only
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
An agent-facing caller set search's mode, which only the brain's operator chooses.
The request itself was wrong or no longer matches the brain; nothing was changed.
Omit mode; for keyword-only matching with a total and paging, pass match: "keyword".
agent
repeat the read that failed
1
no
search_offset_over_cap
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A search offset was over the 10,000 limit.
The request itself was wrong or no longer matches the brain; nothing was changed.
Page with match: "keyword" and the next object each response returns; a cursor has no depth limit.
agent
repeat the read that failed
1
no
segmented_mirror_writer_gate
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A withdrawal mirror of a page stored in segments waits because a gbrain that cannot read its recovery record, and that doctor segmented_storage still warns about, wrote to this brain in the last 7 days; the withdrawal is committed and the canonical file keeps the withdrawn row until the mirror runs.
The mirror's version 2 recovery record names a streamed staging file; a gbrain below the segmented writer floor (v0.60.290.0) misreads it and wedges the worktree, so no record is written while the segmented-storage writer gate sees such a live writer (this host's own pre-upgrade writes, superseded by the upgraded build, do not count). The mirror retries, parks, and runs again by itself once the gate clears.
Only the brain host's operator can resolve this. Tell the user the message and run gbrain doctor --json on the brain host.
A live serve or resident worker on this host runs an older gbrain build than this checkout: its persistence_consumers heartbeat version is below this binary's VERSION.
Upgrading or pulling the checkout does not restart the processes already running from it, so one-shot commands from the checkout (gbrain sync, bun run src/cli.ts) run newer code against the older consumer until serve and its workers restart. A serve older than the heartbeat table writes no row; consumers_without_heartbeat names it.
Restart serve with the command the check prints (systemctl --user restart gbrain-serve.service, launchctl kickstart -k gui/<uid>/com.gbrain.serve, or stop the named pid and start it again), then restart each other listed worker; nothing restarts automatically. Run: gbrain sources writer status --json
gbrain serve --http could not listen: another process already holds that host and port.
A capability this request needs is not configured or not reachable on this brain.
Stop the process on that port, or start the server with another --port and point the harnesses at it.
agent
gbrain doctor --json
1
no
serve_self_exit_suppressed
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
gbrain serve stayed at restart_required past GBRAIN_SERVE_RESTART_REQUIRED_EXIT_SECONDS but did not exit, because it had already exited on its own 3 times within the hour; /health?deep=1 reports self_exit_suppressed.
The opt-in self-exit keeps a durable ledger (serve-self-exit.json under the gbrain home). A serve that reaches restart_required again right after every restart has a cause a restart does not fix, so after 3 self-exits in an hour it keeps serving reads and leaves the decision to a human instead of looping.
Run gbrain sources writer status --json and gbrain doctor --json, report both with the serve log lines, then restart serve by hand.
gbrain serve exited on its own because its persistence consumer reported restart_required continuously for GBRAIN_SERVE_RESTART_REQUIRED_EXIT_SECONDS.
Opt-in (off by default, at least 120 s): a supervisor that restarts on failure, such as the installed gbrain-serve service, then starts a fresh serve without a human. Cleanup is bounded (5 s) because the consumer's stop waits on the stuck work, so the process exits even when it cannot drain. Abandoned claims lapse with the exited process's heartbeat; journaled writes resume on the next owner.
Let the supervisor restart serve; if it exits this way again soon after, run gbrain doctor --json and gbrain sources writer status --json and report both with the exit line.
A managed sync settled a file at the same level in three consecutive passes, but the next round never classified it settled, so the file is held instead of being re-imported every pass; the rest of the source synced.
A pass records the level it settled each path at and the next round expects the same path to classify settled at that level. A path that keeps coming back unsettled at one level points to a broken writer, a stuck effect or a damaged record, not to the file; re-importing it every pass would spend work without converging, so after three passes sync holds it and stamps the rest.
Run gbrain doctor --json and gbrain sources writer status --source --json (both read-only), fix or report what they name with the gbrain version, then gbrain sources retry-held and gbrain sync --source --no-pull. Run: gbrain doctor --json
gbrain setup --serves several would turn a brain that serves one person shared while it holds pages no rule restricts, and nobody chose what happens to them, so setup wrote nothing.
Each member key setup mints reads every page no rule or readable_by restricts, so the owner's journal, DMs, chat, mail and conversation archive would reach every member; only the admin can decide that.
Run setup again with --labelled-only to keep that history private (each member reads only pages labelled for them) or with --open-history to let the members read it. Run: gbrain doctor --only open_shared_pages --json
agent
repeat the read that failed
1
no
setup_hosted_connection
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
This machine already reaches a hosted brain, so gbrain setup will not create a second, local brain.
A new local brain would split memory: sessions would read and write the empty local brain while useful memory stays on the hosted one.
Correct the request using the message above, then retry. Run: gbrain doctor --only harness_wiring --json
Another owner holds what gbrain setup would change: a live server owns this PGLite brain, or the harness configuration holds an entry setup did not write.
A PGLite brain has one writer, so a second server would fail on its lock; an entry setup did not record by hash is the user's or another install's and is never overwritten.
Correct the request using the message above, then retry. Run: gbrain setup claude-code --dry-run --json
gbrain setup for one person was run on a brain that serves several people, and neither this harness's entry (--stdio-member) nor config mcp.stdio_member binds its stdio connection, so setup wrote nothing.
On a brain that serves several people an unbound connection reads every page no rule restricts, for whoever is asking; setup never writes one.
Run gbrain setup --serves several --members <id,...> to label each person; add --stdio-member only for a harness that one person alone uses. Run: gbrain access serves --json
agent
repeat the read that failed
1
no
setup_serves_unreadable
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
gbrain setup could not read whether the existing brain serves several people, so it wrote nothing.
Setup writes an unbound connection only on a brain it knows serves one person; a brain it cannot read might serve several.
Run gbrain access serves --json to see why the brain cannot be read, fix that, then run setup again. Run: gbrain access serves --json
agent
repeat the read that failed
1
no
shared_skills_unavailable
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The shared-skills operation was refused.
A capability this request needs is not configured or not reachable on this brain.
A required capability is not available on this brain. Run gbrain doctor --json to see what is missing.
agent
gbrain doctor --json
1
no
shared_skills_unmanifested
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A conflict in the v0.53.0 shared-skills migration: a source's skills/ folder holds skills but the source has no skillpack.json declaring them, so the migration left them as they are.
Adopting skills nobody declared could publish private or half-finished ones, so the migration never adopts them and records the source as a conflict until a person decides. The conflict affects only shared-skills adoption; every other command works.
Review the skills in that source's skills/ folder with the user, then either declare the ones to share in a skillpack.json at the source's root, or keep the source out of shared-skills adoption with gbrain sources shared-skills <id> off. Run: gbrain apply-migrations --dry-run --json
The server does not expose the shared-skills protocol.
A capability this request needs is not configured or not reachable on this brain.
A required capability is not available on this brain. Run gbrain doctor --json to see what is missing.
agent
gbrain doctor --json
1
no
skill_asset_not_found
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The requested file is not in the approved revision manifest.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
skill_bundle_required
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Import cannot publish skill paths.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
skill_candidate_invalid
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The optimized candidate changed protected frontmatter or has an empty/invalid body.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
skill_catalog_mismatch
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The skill catalog was built from a different skill list than the caller expects (expected_catalog_hash / --expect-catalog), so no suggestion was made and no session state was committed.
A block built from another skill list could name skills the harness cannot load.
Rebuild the catalog from the current skill list (an adapter passes its new snapshot to gbrain skills index build --from-json -), then retry. Run: gbrain skills index status --json
The skill index is damaged or was built by an incompatible gbrain (another index format, ranker or tokenizer), so it was not read.
The request itself was wrong or no longer matches the brain; nothing was changed.
Rebuild the catalog with the command its receipt recorded (gbrain skills index status shows it); a catalog an adapter built from stdin is rebuilt by that adapter. Run: gbrain skills index status --json
A skill resolver setting is out of range (skills.resolver.session_token_budget must be 0 or 100-50000; top_k, min_match, pinned and per_harness must be valid) or GBRAIN_HOME is not an absolute path.
The request itself was wrong or no longer matches the brain; nothing was changed.
Fix the value in config.json under skills.resolver (default budget 2000), or GBRAIN_HOME.
config.json exists but cannot be read or parsed, so the skill resolver lane stays silent and setup writes none of its keys (the file is never rewritten).
The request itself was wrong or no longer matches the brain; nothing was changed.
Fix or move config.json in the gbrain config directory (GBRAIN_HOME/.gbrain, else ~/.gbrain; it must be a JSON object), then run gbrain doctor --only skill_resolver. Run: gbrain doctor --only skill_resolver --json
OpenClaw does not list some skills in the agent's skill directories (dropped at load by skills.limits.maxCandidatesPerRoot), so setup leaves them out of the agent's suggestions.
The request itself was wrong or no longer matches the brain; nothing was changed.
Raise skills.limits.maxCandidatesPerRoot in openclaw.json, or split the skill root, then run setup again.
The OpenClaw skill-resolver plugin runs inside the gateway and needs this gbrain home, library and bin on the same machine, but this machine has no openclaw and no OpenClaw state directory.
The request itself was wrong or no longer matches the brain; nothing was changed.
Run gbrain setup openclaw --skill-loading resolve on the OpenClaw host itself.
The OpenClaw skill-resolver library file is outside the gbrain lib directory, not owned by the gateway user, writable by others, or does not hash to the recorded sha256, so the plugin refused to load it.
The request itself was wrong or no longer matches the brain; nothing was changed.
Run gbrain setup openclaw --skills-index-only to rewrite the library; check who else writes the gbrain home.
The installed gbrain CLI is a different version from the library the OpenClaw plugin runs, and a refresh did not bring them in step, so the plugin keeps the last good library and stops retrying for a day.
The request itself was wrong or no longer matches the brain; nothing was changed.
Run gbrain setup openclaw --skills-index-only and read its error.
gbrain setup openclaw wrote the skill-resolver plugin, but OpenClaw has not installed or loaded it: no openclaw on PATH, an openclaw command failed, or plugins inspect does not show it loaded.
A partial install injects nothing, so setup never reports it as success; the files and the state are kept so the remaining commands finish it.
Run the remaining openclaw commands the message names on the OpenClaw host, restart the gateway, then gbrain doctor --only skill_resolver.
The OpenClaw skill-resolver plugin is installed, but one turn through it under Node did not resolve (the library would not load or the worker did not answer).
The request itself was wrong or no longer matches the brain; nothing was changed.
Read the code in the message (a library or worker code), fix it, then run gbrain setup openclaw --skill-loading resolve again.
gbrain setup --skill-loading resolve found no skill to index (or could not build the catalog or wire the hook), so it wrote no config keys and no hook.
The request itself was wrong or no longer matches the brain; nothing was changed.
Add a skill to one of the scanned directories (the message names them), then run setup again.
Retained skill revisions exceed this source storage budget.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
skill_source_invalid
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The --from-json catalog or --routing file is not valid (not JSON, a malformed entry, over 10,000 skills or 8 MB, or a routing file over 1 MB), so nothing was built.
The request itself was wrong or no longer matches the brain; nothing was changed.
Pass a JSON array of {id, name, description, triggers?, routing?, body?, path?, eligible?} objects.
A --dir or --routing path (or, for gbrain skills library, gbrain's own source in a compiled binary) does not exist or cannot be read, so nothing was built.
The request itself was wrong or no longer matches the brain; nothing was changed.
Pass an existing directory (or file) you can read; for the Node library from a compiled binary, download the release asset.
A skillpack update backup does not hash to the journal's pre-update hash, so restore will not write it.
Restore only writes bytes it can prove are the file's pre-update content. Side effects: files restored before this one stay restored; this file and the rest are untouched.
Leave the file as it is, or compare it with gbrain skillpack reference and edit it by hand. Run: gbrain skillpack restore --list --json
A file changed after the skillpack update it would restore, so restore refused.
Restore never overwrites an edit made after the update. Side effects: nothing was restored (a file that changes mid-restore stops the run; files already restored stay restored and a rerun is a no-op for them).
Keep the later edit and restore the rest: gbrain skillpack restore --skip . Run: gbrain skillpack restore --list --json
Another gbrain skillpack command holds the lock on ~/.gbrain/skillpack-state.json.
Scaffold, update, pin and restore read-modify-write the state file one at a time. Side effects: nothing was written by this command. A lock left by a crash is reclaimed after 10 minutes.
Wait for the other command to finish and run this one again. Run: gbrain skillpack restore --list --json
An earlier skillpack update of this skills root did not finish (a crash left its journal pending), so no new update runs.
Some files of the interrupted skill may hold the new version and others the old. Side effects: nothing was changed by this run; --dry-run still previews.
Run gbrain skillpack restore (named in the message), then update again. Run: gbrain doctor --only skillpack_update_incomplete --json
Another gbrain skillpack command holds this workspace's writer lock (.gbrain-skillpack.lock).
One writer per skills root keeps an update and a restore from interleaving. Side effects: nothing was written. A lock left by a crash is reclaimed after 10 minutes.
Wait for the other command to finish and run this one again. Run: gbrain skillpack restore --list --json
Managed sync files a held file as a page whose slug the file does not carry as written, so removing its frontmatter slug: line would not clear the frontmatter_slug_conflict hold; nothing was written.
The content-repair lane judges a held file with the screen managed sync froze it with (#6696). Sync keys a file to the page that records it as its origin (or its path-derived slug) and accepts a slug: line only when it equals the path-derived slug or that page's slug as written. When the page's slug differs from the path-derived slug (an older import that honored the line, or a source in a subdirectory of its Git repository), or the line reaches the page only through an alias, neither removing the line nor keeping it imports the file, so the lane records slug_page_mismatch with both slugs instead of a generic still_invalid.
Make the slug: line of the held file name the page it is filed as exactly (the hold slug in gbrain sources status --json), or move the file to the path that derives that slug; commit and run gbrain sync --source --no-pull. gbrain repair content --source --only
A managed sync of a subdirectory source ran under one slug-root mode while the source pins the other (sources.config.slug_root_mode), so its checkpoint did not advance.
At a subdirectory the two modes give different slugs (git-root keeps the subdirectory prefix, source-root does not), and the pin exists so a later sync never re-namespaces the source; the pages this run wrote already carry its mode. The pin changed after the run was discovered. A source rooted at its repository root never gets this code: both modes give it identical slugs, and its checkpoint keeps the pin it has. Older releases reported this refusal as revision_conflict.
Ask the user which mode the source keeps. To keep the mode the run used, set sources.config.slug_root_mode back to it and run gbrain sync --no-pull --source ; the refused checkpoint is retried by itself. To keep the new pin, preview gbrain repair managed-sync-orphans --source (it lists the refused cursor as slug_mode_refused), apply it with the hash it prints, and run gbrain sync --no-pull --source , which discovers the source again under the pin; the pages the refused run wrote keep their old slugs beside the new ones. Run: gbrain sync status --source '{source_id}' --json
user
repeat the read that failed
1
no
source_binding_required
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A write needs an explicit source binding on this MCP server (--source-guard).
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
source_changed
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The source changed during the operation; nothing was committed.
Covers a replaced, archived or re-bound source and a canonical file that differs from the page's database copy (detail file_database_drift). When that file is a committed Git change sync has not imported yet, the reason is pending_import: a refused remember is replayed once by the sync that imports it, any other write is resubmitted after that sync (docs/guides/write-refusals.md#pending_import). A page that records no file of its own reconciles against the file at its slug path only with gbrain sources reconcile --preview --adopt-slug-path. A canonical file that is gone while its page is live (reason canonical_file_missing, a ghost page) never clears by retrying or syncing: a person restores the file and syncs, or removes the page (docs/guides/write-refusals.md#canonical_file_missing).
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
source_id_taken
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
This source already exists and does not match this exact admitted request.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
source_mismatch
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The request names a different source than the one this serve is bound to; it is refused, never rerouted.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
source_not_ready
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A committed source and approved schema are required.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
source_pages_remain
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A source delete did not cascade to the source's pages, so it was rolled back and the source and its pages are unchanged.
Every source delete relies on the pages -> sources ON DELETE CASCADE foreign key; without it the pages would stay live with no sources row, where no write, export or per-source audit can reach them (#7072).
Only the brain host's operator can resolve this. Tell the user the message and run gbrain doctor --json on the brain host.
host_admin
gbrain doctor --json
1
no
source_profile_no_backfill
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
This source profile disables automatic embedding backfill.
A capability this request needs is not configured or not reachable on this brain.
A required capability is not available on this brain. Run gbrain doctor --json to see what is missing.
agent
gbrain doctor --json
1
no
source_referenced
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
OAuth clients still reference this source.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
source_retire_superseded
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A retried source remove or purge was superseded: its source has since been removed, replaced or changed by another lifecycle operation; nothing was changed.
A remove or purge records the source incarnation it was admitted against before it deletes its first page, so a retry of its request id can never delete the pages of a source re-added under the same ID, and a later lifecycle change to the source (such as a restore) abandons the request. A request refused this way stays refused.
Do not retry this request id. Read the source's current state; removing the current source is a new decision for the user, made with a new request id. Run: gbrain sources writer status --source '{source_id}' --json
agent
repeat the read that failed
1
no
source_root_conflict
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Multiple active sources alias this canonical skill root; resolve ownership before publishing.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
source_root_unreadable
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The source's registered root on its owner host cannot be read as a directory (gone, unmounted, not a directory, no permission or a symlink loop), so gbrain sources canonical planned and wrote nothing.
Converting a source reads its whole checkout; a root that cannot be listed would otherwise surface as a raw filesystem or Git error, or as a missing-checkout refusal whose fix creates an empty repository there.
Restore or remount the directory on the brain host (or make it readable to the account that runs gbrain), compare it with the root gbrain sources writer status --source --json names, then preview again.
Canonical preparation requires a source-content correction; this profile never writes repository files.
Only the operator of the brain host can change what blocks this.
Only the brain host's operator can resolve this. Tell the user the message and run gbrain doctor --json on the brain host.
host_admin
gbrain doctor --json
1
no
source_writer_restricted
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A write to a guest source came from a credential that is not on its writer list (the local CLI, an enforced member, or a removed writer included); nothing was written.
A guest source holds notes saved for people outside the brain; only the writers the brain owner listed create pages there, so nothing else can make a guest's words look like the owner's or change them.
Do not retry. Write to another source; who may write a guest source is the brain owner's decision.
An unscoped search, query, recall or list_pages came back empty and was refused: every source this connection can read (the default source and federated sources) holds no page every reader of that source can read (pages kept to named readers or private do not count; for recall and query, no active world fact either), while other sources on the brain hold such pages it cannot read (not federated, and no source grant).
Answering would return an empty result that reads like a clean miss. The check is one yes/no about the whole brain, independent of the query: whether another source holds pages; it never says another source matches the question. Quarantined pages count on neither side, nor private pages when remote reads exclude them. The refusal names the host command that federates a source or grants this connection the sources it should read; it never names a hidden source and never widens access. A scope that holds pages but matched nothing, a granted token, an OAuth client, a bound connection and a read that names a source are never refused.
Ask the user which source these connections should read; the brain host runs gbrain sources federate <source>, or grants the token its sources with gbrain auth rescope --token <name> --sources <ids>.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
split_unparseable
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Split unparseable.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
stable_channel_unresolved
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Retired: an older gbrain could not name the stable release from the repository's tags alone. This build resolves stable from the published evidence record and reports stable_missing, stable_invalid or stable_unreadable instead.
Since GBRA-224 the stable channel is the default and accepts only a release whose evidence record proves its gates passed on that exact tree; a message with this code came from an older build.
Rerun gbrain self-upgrade --check-only --json on this build; it names the current stable code and its fix. Run: gbrain self-upgrade --check-only --json
The stable channel has no usable release: the published evidence record is missing, malformed, lacks an evidence key its generation needs (soak_run; matrix_run from the matrix cutover on), or names a version whose release tag is not the stable commit. Nothing was installed.
A stable install accepts only a release whose record proves its gates passed on that exact tree; a record that does not prove it is never trusted, and the client never falls back to alpha by itself.
Wait for a maintainer to repair or re-promote stable, or follow every release on alpha: gbrain config set self_upgrade.channel alpha (or the --channel / GBRAIN_RELEASE_CHANNEL override named in the message).
No release has been promoted to the stable channel yet (no stable tag or no published evidence record), so the stable channel has nothing to install. Nothing was installed.
Stable installs only promoted releases; an empty channel installs nothing rather than guess, and the background update check only reports it.
Wait for the first stable promotion, or follow every release on alpha: gbrain config set self_upgrade.channel alpha (or the --channel / GBRAIN_RELEASE_CHANNEL override named in the message).
The stable channel could not be read: the evidence record or the repository's tags did not answer, or the stable tag and the record disagree while a promotion propagates. Nothing was installed.
Without a verified answer the client installs nothing and keeps any earlier verified answer for the notice only; the channel is unchanged.
Retry in a few minutes: gbrain self-upgrade --check-only. Check network access to github.com and raw.githubusercontent.com if it repeats.
Interim storage records carry fields a card refuses (a command, an unknown field, or a field stamped by gbrain), and the adopt apply did not name each one with --drop-field; nothing was written.
Adopting leaves those fields out of the card, so the user decides; the original pages keep them until finalize soft-deletes the originals.
Show the user the refused fields the adopt preview lists; with their agreement, run the apply the refusal names, which drops each with --drop-field.
Usually a dropped connection or a failed statement; the same error after a rerun is not transient. reason: database_contention: a write admission that deadlocks, serialization failures, lock timeouts or statement timeouts kept refusing for its whole retry budget; no receipt was confirmed, so the same request_id is safe to retry once the contention clears. detail: persistence_mode_unknown (#6482): the persistence_brain singleton is missing, duplicated or carries a non-boolean enabled, so gbrain cannot tell whether the brain is managed and refuses every write, sync, connector run and activation step that depends on it rather than route a managed brain through the unmanaged writer; only a well-formed enabled: false row selects the unmanaged path.
For persistence_mode_unknown: run gbrain sources writer status --probe --json on the brain host (it reports the malformed state instead of refusing), fix the persistence_brain row it names, then gbrain doctor --json.
This brain has no storage shelf to write to (or the storage source ID belongs to another source); nothing was written.
On a brain with a Git checkout the shelf is a hosted git-canonical repository, created only after the user previews it, and hosting needs managed persistence. A repo-less brain gets its database-only shelf on the first register.
Preview gbrain storage init --dir --dry-run and apply the command it prints after the user agrees.
A storage card failed validation (a missing or malformed field, a command field, or a field gbrain stamps itself); nothing was written.
Every card must say where the item is, how big it is and how to restore it, and carries no commands, so a card is complete and safe to act on when it is found months later.
Fix the field the message names and send the card again; gbrain storage-register --help lists the card fields. For an adopt blocked on access_pending or access_unpreservable, settle the access rules over the interim page (gbrain access status) or give it readers its folder rules also list, then preview again. For truncated, move the ## Record section to the top of the interim page.
A storage card field looks like a secret or has a credential shape; nothing was written and the value is not echoed.
Cards are read by agents and copied into the stores; credentials stay in the environment of the skill that restores an item.
Remove the secret, environment assignment, credential variable, URL password, signed-URL parameter or credential-named field from the card; a credential-named field that holds no credential can be renamed to end in _id, _ref or another suffix the rule passes.
The object store an engine opened from settings names did not answer a file check (file_register, file_verify, file_url), so nothing was recorded and no file was reported missing.
A failed read says nothing about whether the object exists; reporting it missing could lead a host to re-upload or delete a file that is still there.
Check the store named in settings.storage (its path, or its endpoint, bucket and keys), then call again.
A git-canonical source (config canonical: git) was written on a brain without managed persistence; nothing was written.
A strict source is committed to Git before the database indexes it, and only managed persistence (the writer coordinator) does that; the legacy writer of an unmanaged brain writes the database first.
Ask the user whether to turn on managed persistence for this brain, or to remove canonical: git from the source.
sync.admission is not normal, so managed sync admits less than it classifies: imports_only admits no deletes and no keep_db writes (they wait as paused_deletes and paused_keep_db), and classify_only writes and stamps nothing.
The owner sets the switch on the brain host (gbrain config set; it is never settable remotely) as the first response to a suspected sync bug. A pass reads it at pin and in every group's admission, and a destructive request re-reads it at publication, so the change applies at the next group; sync status --json reports admission: {value, set_at, effective}, where effective turns true once no pass pinned before set_at holds the lease and no delete or keep_db reconcile admitted before it is unpublished. Doctor warns, with the value's age, for as long as it stays restricted.
Tell the user how long ago the switch was set and ask whether its reason still holds. Only they restore it: gbrain config set sync.admission normal on the brain host; the next sync admits what waited. Run: gbrain config set sync.admission normal
user
gbrain doctor --only sync_admission_restricted --json
1
no
sync_anchor_relative
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Sync refused: the source's stored directory (sources.local_path, or sync.repo_path) is a relative path such as ".", which names whatever directory gbrain runs from.
A relative stored path cannot prove which folder is the brain. Before #7630 a sync run from an unrelated folder treated that folder as the brain repo: it Git-initialized it, committed everything in it and imported its markdown. gbrain now refuses before any Git probe or import, and nothing is changed.
Ask the user which directory holds the source, then gbrain sources set-path ; or clear the pointer with gbrain sources set-path --clear. A path that is absolute only on another operating system (a Windows drive path read on Linux or macOS) is refused the same way; set-path fixes it and --clear does not apply.
Another sync run of the source replaced the managed-sync cursor before this checkpoint published, so the checkpoint had nothing left to publish.
The replacing run (a rediscovery that retried a recorded failure, or a newer sync of the source) covers the source from its own discovery; the superseded checkpoint's receipt is a conflict, no managed-sync failure is recorded for it, and the run that awaited it goes on with the winning cursor. A same-run index lag still reports revision_conflict.
Nothing to repair: let the current sync finish. gbrain sync status --source --json shows the cursor that now covers the source.
agent
repeat the read that failed
1
no
sync_deadline_stalled
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A gbrain sync reached its progress-aware deadline having committed nothing (no page written, deleted or renamed, no cursor advanced), so it stopped as a stall instead of extending.
The deadline extends only while a run commits work. Screening unchanged files, held files and legacy-sweep slices are not progress, so a run that spends its whole deadline on them reports a stall with its cause instead of "still progressing" or a clean resumable stop; rerunning the same way commits nothing again.
Run gbrain sync status --source --json (read-only): it names the step, holds and last error the source is stuck on. Fix what it names, then rerun the same sync. Run: gbrain sync status --source '{source_id}' --json
agent
gbrain doctor --json
1
no
sync_drain_lease_held
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Another process holds the source's drain lease and is still committing pages; this run followed it until its own budget ended, or lost the lease mid-pass, and stopped resumable.
One managed drainer per source: two drainers on one cursor raced each other's checkpoints. A follower counts the holder's commits as its own progress, takes the lease when the holder releases it, and stops drain_stalled (cause no_progress) instead when the holder commits nothing for 5 minutes, so a wedged holder never reads as a clean exit.
Rerun next.command after next.retry_after_ms (safe_to_loop), or let the holder finish; Ctrl-C while following leaves the holder running.
A source's first sync is running (it holds a live sync lock inside the staleness ceiling) and no successful sync is recorded yet, so doctor sync_freshness warns instead of reading it as fresh.
A sync stamps last_sync_at only when it succeeds; a running sync is not a fresh source, and starting a second one beside it only contends for the lock. Over the staleness ceiling the lock reads as wedged (fail) instead.
Wait for the running sync, then run gbrain doctor --only sync_freshness --json again.
A sync is running on this source, or a write in flight or the sync's frozen manifest still names the file a repair would write.
A repair that changed a file the running sync admits later would make that entry refuse on its raw hash, and a file a write in flight names would be written twice; so the one candidate waits while the rest of the source is repaired. candidate_in_flight: the file is named; busy_set_unreadable: the busy set could not be read, so every candidate waited.
Nothing to do for the repair: the next run reads the file again. To finish the sync now: gbrain sync --source --no-pull.
No successful sync is recorded for a source (last_sync_at is NULL) and no sync of it is running; doctor sync_freshness fails with the last attempt's time, result and held files.
The attempt comes from the newest sync job and, on a managed brain, the source's sync status (read-only). reason names the state: no_attempt (nothing recorded: run a sync), attempt_queued (a job is queued: wait), holds_pending (held files: inspect them first), last_attempt_unsuccessful (inspect the job or failure, then retry).
Follow the check fix: it waits, inspects holds (gbrain sync status --source --json) or retries (gbrain sync --source ) depending on the state.
Sync does not apply to this source: its directory is not a Git checkout.
Sync imports changes between Git commits. A gbrain-owned content directory (created by init) holds files gbrain manages itself and is not a Git repository, so there is nothing to sync; gbrain never initializes Git on its own. reason: plain_directory (#7973): a plain directory registered with sources add --force is not a Git checkout, so the managed Git path refuses it; gbrain sync --source <id> imports its files without Git. reason: checkout_missing: a source that has synced from Git and whose root is no longer inside a Git checkout is refused, so its pages are not overwritten by an import; the user restores the checkout.
Correct the request using the message above, then retry.
Sync stopped because gbrain would hold a file whose exact bytes imported before; this is a gbrain bug.
The upgrade invariant says a newer reader never refuses bytes an older one imported; with GBRAIN_SYNC_PARSER_REGRESSION=stop set for the process that syncs (the default holds the file), the run stops without advancing rather than hide a regression.
Report it with the gbrain version, the file and the code; upgrade or pin the last good version, then run gbrain sync --source --no-pull.
host_admin
gbrain doctor --json
1
no
sync_pass_superseded
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A sync pass's checkpoint did not publish because the pass that admitted it no longer holds the source (it ended, or another pass started); the next pass stamps its own checkpoint.
A pass's checkpoint is bound to its drain lease and pass row, so it can never publish after that pass ends. Its receipt is a conflict that records no managed-sync failure and reads superseded in gbrain sources writer failures; a pass that stops with the checkpoint still pending reports disposition superseded instead of a request to resume.
Nothing to repair or resubmit: the pages the pass committed stand. Let the next sync pass run (gbrain sync --source --no-pull), and read gbrain sync status --source --json to confirm the source converges.
agent
repeat the read that failed
1
no
tag_too_long
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A page's tag is longer than the 2688 bytes a tag can be, so nothing was written (sync holds the file).
Tags are stored in a btree index whose entries are at most 2704 bytes; a longer tag would fail the database insert (error 54000) and report a storage failure instead of naming the tag (#7052). The message names the tag's position and size, never its text.
Shorten that tag or split it into shorter tags, then write the page again (for a file: edit it, commit and sync).
The end of the page no longer has the sha256 the append expected, so nothing was appended.
append_page's expected_tail_sha256 binds an append to the tail its caller read; another write changed it, and appending anyway could interleave text with a tail the caller never saw.
Read the page again (get_page body: 'none' returns tail_sha256), check whether the text is still missing, and append against the current tail with a new request_id. Run: gbrain get --source '{source_id}' -- '{slug}'
agent
repeat the read that failed
1
no
tail_exposure_approval
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A fence on a world-visible page has no end marker and prose follows its table; closing it after the last row is safe for the table but makes those lines visible to remote readers, so the content-repair lane previews the close and waits for a hash-bound approval instead of applying it unattended.
Everything after an unpaired begin marker is hidden by the privacy boundary. The repair model read the tail as prose (not rows), so the only judgment left is whether those exact lines may become visible, and that is the user's: the preview prints them and the hash binds them. On a private page nothing new is disclosed and the lane closes the fence by itself.
Show the user the preview's exposed lines (gbrain repair content --source --only
A takes fence row number is already used by a different take that is not in this page's canonical fence.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
target_escape
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The skill target must remain within its selected root.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
timeline_comment_markup
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A stored timeline row carries HTML comment markup, so gbrain keeps it database-side and never writes it back into the page; clean it with gbrain repair timeline-comments.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
A remote put_page or put_pages entry has no Timeline section and would delete the page's dated entries; resend it with the section or with drop_timeline: true.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
The operation did not finish within its time bound.
A temporary condition (a lock, a pending write, a rate limit); the same request can succeed later.
Wait briefly, then retry the same request (writes: reuse the same request_id).
agent
repeat the read that failed
124
yes
topology_change_required
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Adding this source would replace or overlap another owner root.
Only the operator of the brain host can change what blocks this.
Only the brain host's operator can resolve this. Tell the user the message and run gbrain doctor --json on the brain host.
host_admin
gbrain doctor --json
1
no
transcript_secret_exposure
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Imported conversation pages may still carry a typed credential from before the labeled-credential detector, or the last audit found some; pages are never rewritten automatically.
Re-ingest skips unchanged sessions, so pages imported before the detector keep any password typed in prose until someone reviews them.
Run the read-only audit to list affected slugs (never values), then review, edit or (after asking the user) remove each page, and ask the user to rotate any real credential. Run: gbrain transcripts audit-secrets --json
agent
gbrain doctor --only transcript_secret_exposure --json
An explicit atom retry was refused before it started: its transcript does not resolve to the retry's source (a captured session of another source, a session with no known source, or a transcript outside the session corpus on a source other than default).
A batch that failed before session routing may hold another source's session transcript; retrying it would write that session's atoms into the wrong source. Captured sessions resolve through their stamp, frozen record or the registered path containing their cwd, and nothing falls back to the retry's source.
Run the atom drain for the source the session belongs to (corpus_source_other), or map a held session with gbrain sweep --assign-corpus (preview first) and run that source.
Dream triage did not re-judge a transcript because its last judge verdict was truncated, refused or unparseable and its backoff has not ended.
An unreliable verdict is never cached, so without a backoff the same input was paid for every cycle; it waits 24h, doubling per repeat up to 7 days, and a content or triage-model change re-judges at once.
Leave it (it is retried after the backoff), or ask the user before gbrain dream retriage --force, which re-judges every transcript now and pays per file. Run: gbrain dream retriage --dry-run --json
agent
repeat the read that failed
1
yes
trust_raise_refused
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A write tried to raise the trust tier of a fact, take, page or timeline entry without the owner's confirmation, so nothing was changed.
Only the owner can make memory more trusted: confirming on an interactive terminal, or through a connection that holds the memory_confirm scope. The database refuses any other raise so a bug or an agent write cannot promote its own content.
Do not retry. Ask the user to confirm the row themselves on the brain host (gbrain trust confirm ), or leave its tier as it is.
user
repeat the read that failed
3
no
trusted_local_only
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The operation runs only from the trusted local CLI on the brain host; no MCP connection can call it.
Only the operator of the brain host can change what blocks this.
Ask the user to run the named gbrain command on the brain host.
host_admin
gbrain doctor --json
1
no
turn_hook_not_loaded
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The per-turn hook that puts "check gbrain first" next to every user turn is missing, untrusted, or does not load in the harness.
Agents use the brain when that rule reaches them on every turn; registering the MCP server or writing an instruction file alone leaves them answering without it.
Correct the request using the message above, then retry. Run: gbrain doctor --only harness_wiring --json
Two resident gbrain processes on this host (serve, sync, jobs, autopilot or mcp) have each run a full persistence consumer for longer than 30 s, so both claim writes on the same roots.
One full consumer per host is a preference, not a fenced role: a serve always starts full, every other resident kind defers to the first live full consumer it finds in persistence_consumers, and two processes that start within one renewal of each other, or a CLI that took its consumer before the serve started, both stay full until one exits. Every observed preparing wedge had two consumers alive on the host. Short-lived commands (put, import, dream, cli) and rows younger than 30 s are listed, never warned.
Let the shorter-lived of the two finish (a sync CLI run ends on its own) or restart it so it defers; with persistence.single_consumer off, this is the configured behavior. Run: gbrain sources writer status --json
A required dependency or capability cannot serve this request.
A capability this request needs is not configured or not reachable on this brain.
A required capability is not available on this brain. Run gbrain doctor --json to see what is missing.
agent
gbrain doctor --json
1
no
unclosed_ambiguous_tail
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A fence has no end marker and text follows its table, and the repair model read that tail as table rows written without pipes or could not tell, so gbrain will not choose where the fence ends; nothing was written.
Closing after the wrong row would hide rows behind the privacy boundary or expose text; a deterministic rule cannot place the end marker and the model declined to, so a person decides. The attempt memo keeps the same bytes from costing a second model call.
Read the page (gbrain get --source -- ), add the end marker after the last real row of the named fence (moving any rows the tail holds into the table), commit, then gbrain sync --source --no-pull. The preview (gbrain repair fences --source --only
A canonical file a write was publishing (or its file mode) matches neither its recorded prior nor its published bytes, so recovery left it untouched and its worktree stays blocked.
Something outside gbrain edited, split or restored the file while its write was publishing or recovering; gbrain never overwrites bytes it cannot account for.
Do not delete the file to unblock it. Inspect the owner (gbrain sources writer status --json shows the request and its blocked reason) and ask the user which version to keep: the bytes on disk, or the request's recorded prior or published bytes. Run: gbrain sources writer status --json
user
gbrain doctor --json
1
no
unexpected_staging_bytes
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Recovery staging has unexpected bytes or identity; the root and its recovery capacity remain reserved.
The server failed; this is not a caller mistake.
Server-side failure, not a caller mistake. Run gbrain doctor --json on the brain host; if it repeats, report it to the user.
host_admin
gbrain doctor --json
1
no
unknown
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
An unclassified failure (legacy StructuredError fallback code).
The server failed; this is not a caller mistake.
Server-side failure, not a caller mistake. Run gbrain doctor --json on the brain host; if it repeats, report it to the user.
host_admin
gbrain doctor --json
1
no
unknown_command
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The CLI has no command by that name.
The request itself was wrong or no longer matches the brain; nothing was changed.
Run gbrain --help for the command list.
agent
repeat the read that failed
2
no
unknown_flag
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The command does not accept one of the flags passed.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
2
no
unknown_method
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The JSON-RPC method is not supported.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
unknown_source
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The named source is not registered or is archived.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
unknown_tool
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The named tool does not exist or is not callable on this connection.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
unknown_transport
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The caller's transport could not be identified.
A capability this request needs is not configured or not reachable on this brain.
A required capability is not available on this brain. Run gbrain doctor --json to see what is missing.
agent
gbrain doctor --json
1
no
unmanaged_database_path
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
gbrain backup create refused before writing anything: the PGLite data directory is not the managed <root>/.gbrain/brain.pglite (a flat config home, or a path reached through a symlink).
The archive records the managed root it can restore into and refuses to follow a symlink out of it, so a flat or aliased layout cannot be archived without risking a restore into the wrong place.
Take a quiesced physical copy into a new managed root (<new-home>/.gbrain/brain.pglite); the copy is then a normal layout that gbrain backup create accepts while it is under the 8 GiB cap. Run: gbrain doctor --json
Reclone only replaces a checkout created and managed by GBrain.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
unpriced_model
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The configured decide model has no price, so its spend cannot be metered; nothing was sent.
A typesafe:<model> id that gbrain ships no tariff for (a gateway-fronted or self-hosted Jev) would otherwise be admitted as $0 against decide.budget.daily_usd and its remote share, and the spend ledger would record $0 for a real bill (#5980).
Register the price the endpoint bills with gbrain pricing set typesafe:<model> --rate <usd-per-1M-input-tokens> --source <pricing-page-url>, then gbrain decide probe. Run: gbrain pricing list --json
The source contains data this export path cannot carry.
A capability this request needs is not configured or not reachable on this brain.
A required capability is not available on this brain. Run gbrain doctor --json to see what is missing.
agent
gbrain doctor --json
1
no
unsupported_mutation_protocol
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Prepared mutation does not match its accepted target.
A capability this request needs is not configured or not reachable on this brain.
A required capability is not available on this brain. Run gbrain doctor --json to see what is missing.
agent
gbrain doctor --json
1
no
unsupported_path
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Classic sync held a file whose name is not valid UTF-8 or contains a control character, so it cannot be a page path; the rest of the source synced.
Git stores a name as bytes and a page path is text, so importing a lossy decoding would store a path no file has. The hold key spells the exact bytes (/gbrain-bytes/ plus %XX escapes), the message names an item id bound to them, and the hold re-screens on every sync and clears once the name leaves the tree.
Rename the file to a valid UTF-8 name without control characters (the hold's fix spells the old name with printf escapes, never raw bytes), commit, then run gbrain sync --source --no-pull.
gbrain git commit-push --untrack in a managed canonical worktree was refused before the index changed: a file to untrack is not under a storage.db_only dir that the source's gbrain.yml (in the folder the source is rooted in) declares at HEAD and on disk, .gitignore does not ignore it, it is a symbolic link out of the dir, it is a Markdown page whose slug falls outside the dir, or it is a code-extension file that is a page, or that a code-importing source's sync imports as one, or that the source's last finished sync has not seen at its current version; or the brain, which records the source's folder, could not be read, which refuses every file.
The next sync deletes the page of a file that leaves Git unless sync keeps it as database-only, which it decides by page slug, and a file .gitignore does not ignore can be committed again by any later commit.
Follow the fix the refusal prints for each file: declare the folder under storage.db_only in the gbrain.yml the refusal names and its / line in .gitignore (commit both with gbrain git commit-push -m -- .gitignore), add the .gitignore line, declare the slug spelling, keep code-file pages tracked, run gbrain sync --source for code files sync has not seen yet, or retry once the brain is free; then rerun the untrack.
The upload session passed its idle or hard deadline before it was committed, so its parts were discarded and nothing was written.
Open sessions hold staged bytes against per-connection and per-brain quotas; persistence.limits.upload_idle_seconds (1 h) and upload_max_seconds (24 h) bound how long they may.
Begin the upload again with a new request_id and send every part from part 0.
agent
repeat the read that failed
1
no
upload_not_found
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
No open upload session matches this upload_id for this connection.
A session answers only its creating connection, in its source, while the page it began against is unchanged; every other case gets this same answer so an upload_id reveals nothing.
Begin a new upload with begin_page_upload and a new request_id.
agent
repeat the read that failed
1
no
upload_protected_content
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A remote replace upload over 24 MiB was refused because the page holds content it cannot carry over: a takes fence or facts rows remote reads hide, or timeline rows.
put_page keeps a hidden takes fence and hidden facts rows and checks omitted timeline rows by comparing whole bodies; an upload over the single-string ceiling is never held whole, so it refuses instead of dropping them.
Replace the page with content of at most 24 MiB through put_page, write it locally on the brain host, or (timeline only) commit with drop_timeline: true when deleting every entry is intended.
agent
repeat the read that failed
1
no
Reasons: takes, facts, timeline.
upload_too_many_parts
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
An upload part was refused because the session reached its part limit (64 plus one per 64 KiB of total_bytes) without completing the content.
Each part is a stored row; the limit keeps a session of tiny parts from growing without bound, and a client cutting parts near part_max_frame_bytes never reaches it.
Send the rest of the content in that part (within part_max_frame_bytes), or abort and begin again cutting parts near part_max_frame_bytes.
A classic source's pull cannot fast-forward: the checkout has commits that are not on the upstream and the upstream moved forward; local HEAD keeps syncing.
The upstream still contains the commit this checkout last pulled, so nothing was force-pushed: bringing the upstream in beside the local commits loses nothing.
Run gbrain git commit-push --pull --path , then gbrain sync --source .
A classic source's upstream was force-pushed: the upstream commit the checkout last contained is not in the new upstream history, so the pull cannot fast-forward; local HEAD keeps syncing.
Merging would bring back the commits the force-push removed, so the fix resets the checkout to the new upstream after the user agrees, keeping the old history under a backup ref.
Ask the user, then run the gbrain sources reset-upstream --expect-local --expect-upstream command doctor sync_failures prints (preview with --dry-run), then gbrain sync --source .
A classic source's checkout and upstream diverged and gbrain has no record of the upstream before the fetch (first pull after an upgrade, or the recorded commit is gone), so it cannot tell a force-push from local commits; local HEAD keeps syncing.
Merging could bring back commits a force-push removed; the reset preview names any local commit that was never on the upstream before anything moves.
Ask the user, then preview the gbrain sources reset-upstream command doctor sync_failures prints with --dry-run.
An as_of read found no version of the page that declares a readable valid_from, so no edition can be placed on the date.
Valid time comes only from the valid_from / valid_until frontmatter the page carries; gbrain never infers when text took effect. Only the user knows the date, so the fix asks them before a templated edit_page records it.
Ask the user when the text took effect and record it as a quoted valid_from (the fix carries the edit). For what the brain had recorded at a time, read with known_as_of instead.
gbrain embeddings prewarm was refused before reading anything because the pg_prewarm extension is not created in the brain's database (or the server does not ship it).
Prewarm loads index pages into shared_buffers with pg_prewarm, the Postgres contrib function for exactly that; creating an extension needs a database owner or superuser, so gbrain never creates it itself.
Ask the database administrator to run CREATE EXTENSION IF NOT EXISTS pg_prewarm; (install the PostgreSQL contrib package first if the server lacks it), then rerun gbrain embeddings prewarm.
gbrain embeddings prewarm was refused because the brain is PGLite; nothing was read.
Prewarm fills a Postgres server's shared_buffers so later processes find index pages cached; PGLite runs inside each gbrain process, with no server cache that outlives it.
gbrain embeddings prewarm was refused before reading anything because the brain's HNSW indexes are larger than half of shared_buffers.
Prewarm loads the indexes into shared_buffers, the cache Postgres sizes and keeps; past half of it the prewarm would evict heap and keyword-index pages other reads need, so the next searches would pay first-touch reads on those instead. effective_cache_size does not decide: it is a planner hint, not memory the server holds.
Raise shared_buffers on the database host to at least twice the index size the message names and restart Postgres, or leave the indexes cold; read the fit with gbrain embeddings prewarm --dry-run --json. Run: gbrain embeddings prewarm --dry-run --json
Source content or relationships changed during verification.
The server failed; this is not a caller mistake.
Server-side failure, not a caller mistake. Run gbrain doctor --json on the brain host; if it repeats, report it to the user.
host_admin
gbrain doctor --json
1
no
visibility_noncanonical
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A file asks for visibility: private in a spelling page privacy does not read, so sync or import held it instead of storing it world-readable.
Page privacy reads only the exact lowercase key and value visibility: private. A file that spells it another way (Visibility: private, visibility: Private, a block scalar, a list, a flow mapping or a merge key) would be stored as a world page while its author believes it is private (#7848); put_page, edit_page, capture, ingest_capture, brainstorm --save and sources reconcile refuse the same request as visibility_not_applied.
Write visibility: private on its own frontmatter line (lowercase key and value), then commit and sync, or import the file again.
A page write asked for visibility: private, but the page would have stayed world-readable, so nothing was written.
A write that reports success while the page stays world-readable leaves the caller believing it is hidden. Page privacy reads only the exact lowercase key and value visibility: private (#7841). When the frontmatter is unreadable or ambiguous, the write is refused invalid_frontmatter instead.
Read the page and its revision, write visibility: private on its own frontmatter line (lowercase key and value), then submit again with a new request_id. Run: gbrain get --source '{source_id}' -- '{slug}'
The Wakeshift key is missing, mistyped, in an older format, or in a key file other users can read, so reporting back was not turned on.
A Wakeshift key is an Ed25519 private key (wst_ followed by 50 base58 characters whose last four bytes are a checksum). gbrain reads it from WAKESHIFT_API_KEY or ~/.gbrain/wakeshift.key, which must be readable by its owner only; it never stores the key in the database or prints it.
Ask the user to create a key in their Wakeshift console and put it in ~/.gbrain/wakeshift.key (chmod 600) or WAKESHIFT_API_KEY in ~/.gbrain/.env, then run gbrain wakeshift enable again.
user
repeat the read that failed
1
no
Reasons: format, checksum, legacy, file_too_open, missing.
Wakeshift refused the request; the reason carries its error code. Nothing was watched or sent.
Wakeshift checks each request (the signed key, the event and its arguments, the conversation's session key). A refusal other than a rate limit does not go away on retry.
Call wait_job to wait without Wakeshift; the brain owner can run gbrain wakeshift test to check the key and the app.
Reporting back refused (gbrain wakeshift enable, or a watch tool): this brain has live access members and its operator has not set the terms and privacy links Wakeshift requires.
Wakeshift's terms (6.2, 6.6) make the operator show each person its own terms and privacy policy, which refer them to Wakeshift's Connector Terms and Privacy Policy, before the first wake. gbrain shows that step from the two links the owner sets on the brain host.
Ask the brain owner to run gbrain wakeshift enable --terms-url --privacy-url ; meanwhile agents can use wait_job or get_write_request.
gbrain repair file-drift --whole-class settles only --prefer file on held side unknown, database or both, so a --prefer database or deleted-side selection was refused before anything was read.
Letting the database win rewrites files, and each deleted-side state is its own decision; neither is settled for a whole class with one approval.
Preview that selection one window at a time with the per-window command the message names (--held --side --prefer , without --whole-class). Run: gbrain sources status '{source_id}' --json
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
withdrawal_mirror_failed
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A page's Git or embedding work is withheld because its withdrawal mirror failed before rewriting the page's file; the file may still hold the withdrawn text.
A withdrawal's Git and embedding effects touch only the pages whose file its mirror recorded rewriting (GBRA-130 A-12); Git never commits a page the mirror passed without rewriting its file. Retrying the request's effects reruns the mirror for this page; once the mirror commits, the withheld work is re-armed automatically.
Read the parked effects with gbrain doctor --only parked_effects, fix the cause the mirror recorded, then preview gbrain sources writer retry-effects --request-id --dry-run and run it without --dry-run.
agent
gbrain doctor --json
1
no
withdrawal_mirror_pending
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A page's Git or embedding work is waiting because its withdrawal mirror is queued or running again (for example after retry-effects).
Git and embedding work behind a withdrawal mirror touches only the pages the mirror recorded rewriting (GBRA-130 A-12); while the mirror runs, the effect worker releases the work and picks it up once the mirror settles.
Nothing needs resubmitting; read the effects with gbrain sources writer status --json and wait for the mirror to finish.
agent
repeat the read that failed
1
yes
withdrawal_provenance
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The withdrawal target manifest is invalid.
The server failed; this is not a caller mistake.
Server-side failure, not a caller mistake. Run gbrain doctor --json on the brain host; if it repeats, report it to the user.
host_admin
gbrain doctor --json
1
no
worktree_dirty
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A managed sync held a file whose uncommitted working-tree bytes match neither the pinned commit nor the current page; the rest of the source synced and the local edit was not overwritten.
On a live checkout an agent may be mid-edit on a file the catch-up reaches. The bytes are not committed at HEAD, so sync cannot tell a deliberate local change from a stray one, and importing the pinned version would discard the edit; before #6340 this refusal stopped the whole run.
Commit the file (or restore it), then run gbrain sync unblock --source --apply (it re-screens every held file that is now committed) and the same gbrain sync; a later commit that changes the file re-screens it on its own.
A write reached a checkout while gbrain sources refresh was draining, fast-forwarding or syncing it, so it was not journaled; nothing was recorded.
A refresh fences every source bound to the checkout until its syncs finish, so no write publishes onto a moving HEAD. An interactive write waits out the fence for up to 10 s before this refusal; a refresh tick can hold it for minutes.
Repeat the call with the request_id the refusal names after retry_after_ms (in detail); over MCP, fix.mcp is that call. Nothing was recorded, so the retry cannot write twice. gbrain sources writer status --source --json shows the refresh.
A background producer (maintenance, conversation facts, an autopilot phase or an autopilot catch-up sync) stopped admitting writes because a cumulative write cap is past persistence.capacity.background_pause_pct (default 80); interactive writes keep the rest. Nothing was submitted and no receipt was written.
Near a cumulative cap the remaining request ids and receipt bytes are kept for the user's own writes (remember, put_page, edit_page, operator sync, approved repair). Request ids are never freed, so past the line on ids only the brain host's config raise resumes background work; receipt bytes also free as receipts compact.
Only the brain host's operator can resolve this. Tell the user the message and run gbrain doctor --json on the brain host. Run: gbrain doctor --only persistence_capacity --json
A cumulative write cap is at or past 80% or runs out within persistence.capacity.warn_days (30) days at its 7-day rate; writes still work.
Request ids are permanent and receipt bytes free only as receipts compact, so the cap is raised before admission refuses.
Only the brain host's operator can resolve this. Tell the user the message and run gbrain doctor --json on the brain host. Run: gbrain doctor --only persistence_capacity --json
A temporary condition (a lock, a pending write, a rate limit); the same request can succeed later.
Wait briefly, then retry the same request (writes: reuse the same request_id).
agent
repeat the read that failed
1
yes
write_gate_rejected
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The write gate refused external instruction-like content because the operator set write_gate.external_mode to reject.
Text from an untrusted source that reads like an instruction to an agent (an override, a standing rule, an exfiltration or credential request) is refused instead of held under that setting, so nothing was written. The same content refuses on every retry.
Tell the user the content was refused; whether to accept it or switch write_gate.external_mode back to quarantine is their decision.
The write gate held this content for the owner's review instead of saving it as memory.
Content from an untrusted source read like an instruction to an agent, so it was quarantined in the write-gate holding table. It is not searchable or recalled until the owner releases it; retrying the same write only re-opens the same hold.
Do not retry. Tell the user what was held and give them the release command from the fix; releasing is their decision.
The database kept ending this managed write's statements (SQLSTATE 57014, a statement timeout or cancel, or 0A000, a plan cached before a migration changed the table), or its publication kept running past persistence.publication_ceiling_ms and was cancelled, after persistence.max_transient_retries retries with backoff (default 5), so the owner finished it failed instead of preparing it again; nothing was published.
Each such interruption throws the write's preparation away. It is load or latency, not the write's content, so it has its own retry budget: the request is claimed again after a backoff (1 s, 2 s, 4 s, 8 s, then 15 s; no claim is held while it waits) up to persistence.max_transient_retries times, and the next interruption ends it instead of preparing it again without limit. It never charges persistence.max_preparation_attempts, which preparations cut off at their deadline keep. Contention with other transactions (lock timeout, serialization failure, deadlock), a dropped connection and a restarting database are never counted. The receipt names the interruptions (attempts), the retry limit, the cause and the SQLSTATE.
Inspect the owner with gbrain sources writer status --source --json (read-only), then submit the write again with a new request_id once the database is less loaded; a held sync file needs gbrain sources retry-held and the same sync. If the same write ends this way again, report its request id with gbrain doctor --json. Run: gbrain sources writer status --source '{source_id}' --json
The database connection dropped while a write was being admitted, and it kept dropping through the re-reads, so whether the write was accepted is unknown.
A session that closes under an admission (a pooler reap, a failover, pg_terminate_backend) leaves the transaction either committed or rolled back with no way to tell from the lost socket. gbrain re-runs the attempt, which starts by reading the retained request_id, so a single drop resolves by itself; this code means the database stayed unreachable through those re-reads. Before #6355 the raw socket error reached the caller, and a receipt oracle took it for a refusal while the write committed.
Read the request first (the fix names it): a committed or pending row means the write was accepted, replay the same request_id to wait for it; no row means it was not, submit it again with the same request_id. Never resubmit under a new request_id without that read.
The write was accepted and is still pending; it may commit later.
A temporary condition (a lock, a pending write, a rate limit); the same request can succeed later.
Wait briefly, then retry the same request (writes: reuse the same request_id).
agent
repeat the read that failed
10
yes
write_quota_exhausted
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A write cap (permanent request ids, reserved receipt bytes, staged upload bytes or open upload sessions, for the principal or the brain) is full, so the write was not admitted and nothing changed.
Request ids are permanent replay protection and a receipt keeps its bytes until it compacts, so waiting does not free the cap; the brain host raises it with gbrain config set (reversible).
Only the brain host's operator can resolve this. Tell the user the message and run gbrain doctor --json on the brain host. Run: gbrain doctor --only persistence_capacity --json
A bulk run (managed sync catch-up, reclone or a repair) estimated more new receipts than the remaining write capacity allows before its producer's pause line, so it did not start; other writes still work.
Starting a run that the cap would stop part way leaves a long tail of pending pages; the preflight refuses up front with the config raise that covers the run.
Only the brain host's operator can resolve this. Tell the user the message and run gbrain doctor --json on the brain host. Run: gbrain doctor --only persistence_capacity --json
Topology changes require an action-specific --admin-intent and the --expected-state from a reviewed writer status.
Only the operator of the brain host can change what blocks this.
Only the brain host's operator can resolve this. Tell the user the message and run gbrain doctor --json on the brain host.
host_admin
gbrain doctor --json
1
no
writer_admin_locked
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Writer administration is locked; deactivation was not applied.
Only the operator of the brain host can change what blocks this.
Only the brain host's operator can resolve this. Tell the user the message and run gbrain doctor --json on the brain host.
host_admin
gbrain doctor --json
1
no
writer_admin_state_changed
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Writer topology changed since inspection; the administrative request was not applied.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
writer_busy
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The canonical worktree is busy with another write.
A temporary condition (a lock, a pending write, a rate limit); the same request can succeed later.
Wait briefly, then retry the same request (writes: reuse the same request_id).
agent
repeat the read that failed
1
yes
writer_coordinator_required
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The operation needs managed persistence (a writer coordinator) on the brain host.
Only the operator of the brain host can change what blocks this.
Only the brain host's operator can resolve this. Tell the user the message and run gbrain doctor --json on the brain host.
host_admin
gbrain doctor --json
1
no
writer_identity_invalid
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The local writer identity is invalid.
Only the operator of the brain host can change what blocks this.
Only the brain host's operator can resolve this. Tell the user the message and run gbrain doctor --json on the brain host.
host_admin
gbrain doctor --json
1
no
writer_identity_publish_failed
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
The replacement writer is durable but its credential file could not be published.
Only the operator of the brain host can change what blocks this.
Only the brain host's operator can resolve this. Tell the user the message and run gbrain doctor --json on the brain host.
host_admin
gbrain doctor --json
1
no
writer_lock_unavailable
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A writer lock could not be taken: another process holds it (busy), or this process cannot open the lock file at all.
Busy clears when the holder finishes. A process that cannot open the lock file (a sandbox, an unwritable lock directory) fails the same way on every retry, so its write stays queued with blocked_reason writer_lock_unavailable until an owner process that can take the lock publishes it; the OS error is kept in the owner-only detail.
For a queued write, wait for the owner (gbrain sources writer status --json names it) or run the write from a process that can open the lock directory; retrying from the same sandboxed process changes nothing. The lock path and the rule that chose it are in onboarding.sources[].coordination_lock of that status. A claim refused while another process repairs an old reservation whose lock was recorded inside the checkout (old_path_wedge: true) succeeds once that repair finishes: run the claim again; never delete the reservation.
agent
repeat the read that failed
1
yes
writer_manifest_mismatch
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Successor checkout differs from the recorded canonical manifest.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
writer_manifest_rescope_required
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
A writer transfer prepared by an older release covers every file of the old checkout, ignored files included, so a clean Git clone cannot match it.
Transfer manifests now cover the files Git tracks, so ignored secrets such as .env files are never read, hashed or required on the successor; a manifest recorded before that change is prepared again instead of asking the user to copy ignored files.
On the owner host, run gbrain sources writer transfer prepare again with its admin intent and state, then accept with the new epoch and manifest.
The canonical worktree manifest cannot be recorded safely: the checkout holds a symlink or a Git submodule, a Git-scoped comparison ran on a directory Git cannot list, or Git cannot read a directory that holds .git.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
writer_not_initialized
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Persistence identity is missing.
Only the operator of the brain host can change what blocks this.
Only the brain host's operator can resolve this. Tell the user the message and run gbrain doctor --json on the brain host.
host_admin
gbrain doctor --json
1
no
writer_not_quiesced
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Older writers or maintenance jobs are still running.
Only the operator of the brain host can change what blocks this.
Only the brain host's operator can resolve this. Tell the user the message and run gbrain doctor --json on the brain host.
host_admin
gbrain doctor --json
1
no
writer_pool_capacity
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Mirror recovery is waiting for publication capacity.
A temporary condition (a lock, a pending write, a rate limit); the same request can succeed later.
Wait briefly, then retry the same request (writes: reuse the same request_id).
agent
repeat the read that failed
1
yes
writer_registration_required
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Writer registration required.
Only the operator of the brain host can change what blocks this.
Only the brain host's operator can resolve this. Tell the user the message and run gbrain doctor --json on the brain host.
host_admin
gbrain doctor --json
1
no
writer_regrant_required
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
This lane already has a different grant.
Only the operator of the brain host can change what blocks this.
Only the brain host's operator can resolve this. Tell the user the message and run gbrain doctor --json on the brain host.
host_admin
gbrain doctor --json
1
no
writer_transfer_conflict
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Writer transfer conflict.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
writer_transfer_required
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Writer transfer required.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.
agent
repeat the read that failed
1
no
writer_upgrade_required
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Apply the canonical writer guard, outbox, and source lifecycle migrations before activation.
Only the operator of the brain host can change what blocks this.
Only the brain host's operator can resolve this. Tell the user the message and run gbrain doctor --json on the brain host.
host_admin
gbrain doctor --json
1
no
wrong_account_consented
Meaning
Why
Next step
Who acts · consent
Verify
Exit
Retryable
Google connect credential error: wrong account consented.
The request itself was wrong or no longer matches the brain; nothing was changed.
Correct the request using the message above, then retry.