Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
295 KB
Raw Blame

Write refusal reasons

When a managed brain refuses a write, sync or background effect, the error names a reason and a recovery command. This page lists the reasons a user or agent is most likely to meet, what each one means, and what to run. None of these refusals overwrites your file or your database copy; each one stops so that nothing is lost.

Say to your agent: "My save was refused with file_database_drift. Show me the preview before you fix it." or "Doctor says effects are parked. What failed, and can we retry it?"

Where the reason appears

A refused operation prints, or returns in JSON, an error with these fields:

{ "error": "source_changed", "detail": "file_database_drift",
  "message": "...", "suggestion": "On the brain host, run gbrain sources reconcile ..." }

error is the error code. detail is the specific reason when one code has several causes. suggestion is the recovery step: usually a command, filled in with the real source and slug where the code knows them, sometimes with placeholders such as <source> or <brain> to fill in, and sometimes an inspection instruction. A failed write receipt (gbrain write-request <id>) carries the error code as write_error and its diagnostic message as write_error_message; managed sync and memory-verb errors add the specific reason. Since #6650 a receipt that ended failed, conflict or cancelled (or still holds a recovery record) also carries write_error_reason (this page's reason), the same suggestion, and a diagnosis: its category, class, safe actions, whether a person decides, whether it is historical, and a structured fix (fix.next, fix.command). To see every such receipt of a source at once, grouped with a fix per group: gbrain sources writer failures <source> --group-by category (terminal write failures). Run recovery commands on the brain host unless the row says otherwise.

Reading persistence_requests directly with SQL? Its error_message column holds only the short message (for source_changed, one line such as "The canonical file was removed outside coordinated publication."); the recovery command lives in the error's suggestion and is not stored there. Run gbrain sources writer failures <source> --group-by category (or gbrain write-request <id> --json for one row) instead: each group and each receipt carries its category and the exit, with the exact command.

Keep the original request_id. Unless a row says to use a new one, retry the original write with the same ID after the fix, so the brain replays it instead of making a duplicate.

Reference

Reason Error code What it means Recovery
file_database_drift source_changed The page's canonical file and its database copy disagree, usually because the file was edited outside a coordinated write. Neither copy was overwritten. The receipt records the cause as error_detail.origin: file_database_drift (GST-1601). A file with no type: line keeps the stored type, and titles compare trimmed, so those alone do not cause this. Drift only in ordinary frontmatter keys (not a policy, privacy, lineage or trust key such as readable_by, derived_from or trust_tier, nor title, type or tags) does not refuse a write that leaves the frontmatter unchanged, such as remember: the write lands and the file keeps its own frontmatter, so that drift is left for reconcile (#8109). With gbrain config set persistence.adopt_local_edits.source.<source> true (off by default), a remember, capture or add_timeline_entry that meets a one-sided local edit (Git HEAD still holds the database copy; on a repo-less brain, any edit) is not refused: once the file has been unchanged for persistence.adopt_quiet_ms (default 5000), the owner commits that file on its own (gbrain: adopt local edit to <path>, trailers gbrain-adopted: and gbrain-author: unknown; page history reason adopted_local_edit), then applies the write on top, and the receipt names adopted. A two-sided edit, a file that does not import, an edit to the title, type or a protected key, put_page and every other verb still refuse; doctor local_edit_adoptions lists adoptions of the last 24 h (GST-1601). The refusal also stays for a file over the page size limit or a page stored in segments, an unmerged path or a merge, cherry-pick, revert, rebase, git bisect (BISECT_LOG) or uncommitted git merge --squash (SQUASH_MSG) in progress, and a stale editor save (a file equal to an earlier stored revision, or missing a Facts or timeline row the last write added); the quiet wait never passes 30 s, since writes behind it on the same checkout wait meanwhile (#8755). It also stays when git rev-parse --absolute-git-dir answers with anything but one absolute, existing directory in valid UTF-8; a git cherry-pick -n leaves no marker, and its staged paths stay out of the adoption's commit (#8826). An adoption whose commit landed before its publication failed is published on its replay even after the write it was made for ended, and one that ends without committing after that commit names it on its receipt (outcome.persistence.git_commit, landed_before_row: true; #8824, #8767). The receipt's fix (gbrain sources writer failures <source>, gbrain write-request <request_id> --json) previews keeping the database copy for that one page with gbrain repair file-drift --source <source> --slug <slug> --prefer database (--prefer file previews importing the file instead); the preview names any file edit or deletion sync never imported that the database copy would overwrite (in bulk such pages are kept, kept_newer_file / kept_newer_delete); a person picks the side, and the apply the preview prints asks for their consent (exit 3), taking --yes only after they agree (newer file changes). A group of such receipts gets --all-drifted --since <instant> with the oldest receipt's time, so only pages that drifted since then are selected. For a hand merge: gbrain sources reconcile <source> <slug> --brain <brain> --preview, review the preview, resolve it, then --apply <resolved-preview-file> --request-id <new uuid>. Retry the original write with a new request ID. A page that records no file of its own (no source_path, typically written by an older release whose write-through also put ingested_via / ingested_at / source_kind in the file only) reconciles against the file at its slug path only when you add --adopt-slug-path to the preview; the refusal names the flag in that case, and apply records that file as the page's origin. See repair a file/database disagreement. Many pages at once: gbrain sources reconcile <source> --brain host --audit --conflicts lists them and gbrain repair file-drift resolves them, preferring the file or the database copy (file drift).
canonical_file_missing source_changed (a caller write; maintenance refuses before admission) The page's recorded canonical file is gone while its database page is still live (a ghost page: the file was moved or deleted outside gbrain). A caller write refuses with "The canonical file was removed outside coordinated publication." and nothing is written; retrying it refuses the same way. A maintenance write (fact-fence adoption, enrichment, dream) is refused before admission: no request id, no receipt (before #6696 each cycle settled a conflict receipt). gbrain sources writer failures <source> reports such receipts as category canonical_file_missing. Neither copy was changed. Decide which copy is right. A visibility edit cannot publish while the file is gone, so to keep the page and only narrow who reads it, add a page rule on the brain host: gbrain access rule add --slug <slug> --readers <member> --source <source> (it previews; --yes applies; list the owner's member to keep the owner reading; removing the rule undoes it; upgrade every gbrain host that shares the brain first). No file is written for the page. If the file should exist, restore it at its recorded path and preview the page with gbrain sources reconcile <source> <slug> --brain host --preview, or sync. If the page should go, preview the ghost-page repair with gbrain repair ghost-pages --source <source> (read-only; it prints the apply command with its hash) and apply it with --apply --expect <hash> --yes only after the user agrees; a soft-deleted page can be restored with gbrain restore <slug> --force until the autopilot purge 72 h later. gbrain pages ghosts --source <source> and doctor ghost_pages list them, doctor maintenance_write_drift lists held-back maintenance writes. See ghost pages.
label_edit_refused label_edit_refused (reason file_differs or label_line) An operator label repair (gbrain repair visibility, gbrain repair private-labels) left a page unchanged because its file holds the page but cannot take the label edit line by line (GST-2603). These repairs change only the label lines and never re-render a file, so a person's formatting and comments survive. file_differs: once its label lines are edited, the file still differs from the page in a real key, named in detail (a frontmatter key such as a date, the title, the type, the tags or the body); stamps gbrain keeps only in the database (a pack-renamed type, validate: false, legacy_type) never count. label_line: the label line has a block or multi-line value or a duplicate key, or the file has no frontmatter block. Nothing was written. The repair counts the page as declined, never toward item_failures_systemic. The next gbrain repair visibility preview holds it under details.held with its next step; gbrain repair private-labels has no held list, so its next preview lists the page again. A file edited outside gbrain: preview it with gbrain sources reconcile <source> <slug> --preview (managed) or run gbrain sync --source <source> (unmanaged), then preview the repair again. A label line: write the label as one plain line (visibility: private), commit it and sync the source.
refusal_breaker the code of the earlier refusals The same maintenance write (same source, slug, page revision, planner and intent) was refused persistence.maintenance.refusal_breaker_threshold times (default 3; 0 turns it off) in the last 24 hours, so maintenance submits nothing for it instead of adding another receipt (#6696). It is tried again once the page, the planner or the write changes, or when the oldest refusal is 24 hours old. Read the last refusal with gbrain write-request -- <request_id> (named in the message) and fix what it names. Doctor maintenance_write_drift lists every held-back write with its exit.
canonical_file_absent source_changed (restore_page / gbrain restore) On a brain without managed persistence, a restore that writes no file (sync.write_through off, a sandbox, a database-only source) of a soft-deleted page whose recorded file is no longer among the files sync imports (#6609). A plain restore would be undone by the next gbrain sync --full, so nothing was restored. Not retryable; the fix asks the user. Ask the user. To keep the page with its file: put the file back at its recorded path, commit it and gbrain sync --source <source>. To keep it database-only: gbrain restore <slug> --source-id <source> --detach (MCP restore_page with detach: true), which forgets the recorded file and stamps database_only_reason='detached'. See restoring a page whose file is gone.
pending_import source_changed (detail file_database_drift, reason pending_import) The page's canonical file holds a change committed through Git (another agent's commit, a pull) that managed sync has not imported yet: the file on disk is exactly the blob HEAD holds for its path and not the one the source's last imported commit holds. The message is "The canonical file holds a committed Git change that sync has not imported yet." Nothing was overwritten. Since #6693 the receipt records origin pending_import; a write refused because sync holds the file records origin sync_held (see held files). A remember needs nothing from the caller: its fix.next is wait, the fact is kept in the receipt, and the first managed sync that imports the file (any outcome, a partial run included) makes one replay attempt on the original caller's lane with the fact's original valid_from and expiry (the sync result's replayedRemembers counts examined, replayed, waiting, skipped, remaining; at most 50 per run and 30 s). Do not save the fact again. A remember refused while sync held its file is replayed the same way once the repaired file is imported. A replay that is refused (authority revoked, page rewritten) stays listed by gbrain repair failed-writes --source <source> for a person. Any other write (put_page, add_timeline_entry) is never replayed automatically, because its body would replace the imported change: wait for the source's running sync owner (gbrain serve, autopilot or a sync job) to import the commit, which the refusal's read-only fix gbrain sync status --source <source> --json shows, then read the page again and resubmit with a new request ID. Neither refusal tells the caller to start a sync, because a second sync beside a running owner competes with it; when status shows no owner running, ask the user to sync the source on its host. An uncommitted hand edit still refuses file_database_drift and needs reconcile. With persistence.refresh_barrier on, a put_page, capture, remember or add_timeline_entry waits for the import instead of being refused (deferred writes).
sync_write_through_off unavailable (forget / forget_fact, detail sync_write_through_off) sync.write_through is off and a canonical file carries the claim. The struck row would not reach the file, so a brain rebuilt from Git would bring the claim back; nothing was withdrawn. A claim that only database-only pages carry is still withdrawn. A sandboxed subagent's forget of such a claim refuses the same way with scope_denied, detail subagent_sandbox. gbrain config set sync.write_through true, then forget the fact again; from a subagent sandbox, forget it from the main session.
shared_origin source_changed (purge, or a delete whose survivor changed); a soft delete commits with write_through.skipped: shared_origin Two live pages of one source recorded the same canonical file (a duplicate-origin twin: the shared file renders one of them, so a delete of either used to refuse file_database_drift, reconcile refused "Several pages claim the recorded canonical file" and every managed sync refused page_identity_changed). A soft delete (gbrain delete <slug> --source-id <id> --expected-revision <rev>) of a page whose file another live page records now keeps the file and publishes database-only: the selected database page is hidden; the file and the surviving page remain. This does not erase that file's contents. The receipt's write_through.warning says so and names the surviving slug to the trusted local owner, or to a remote writer whose grant and visibility cover that slug; other remote writers read a generic "another page of this source records the same file". Sync's census and both origin guards apply one rule: a live page wins over tombstones, several live pages refuse, a single tombstone may be reused, several tombstones stay ambiguous. An owner purge (--purge) of a shared-origin page refuses with this reason: a purge tombstones the content source-wide and a same-content survivor would refuse purged_content on its next import. The 72 h retention purge (the autopilot purge phase, gbrain pages purge-deleted --older-than 72h --yes) of such a page once it is soft-deleted writes no tombstone, so it removes the page row, its chunks, links and facts database-only and leaves the file and the surviving page untouched (#7311); a census that changed under it defers to the next run, which re-reads the claimants and, when the tombstone now owns the file alone, purges it normally, file included. A delete whose surviving claimant changed between preparation and publication (the file moved or removed, a survivor deleted or re-pointed) refuses and never removes the file as a fallback. Delete the page that should not own the file; the kept file still holds whatever text it had, so edit it first if it holds the deleted page's text, then import its current content into the surviving page with gbrain repair file-drift --source <id> --slug <surviving-slug> --prefer file (preview, then the apply command it prints) and gbrain sync --source <id> --no-pull. Sync does not overwrite a surviving page that differs from the file: it holds it file_drift, whose fix leads with the same command. For a purge of a live page, soft-delete it instead; a soft-deleted one is removed by the retention purge (a tombstone an older release parked after its refusals is retried once by the first purge run after the upgrade). After a source_changed on a changed survivor, submit the delete again with a new request_id; it re-reads the file's claimants.
database_guard or database_trigger writer_coordinator_required (or storage_error for another trigger) A database trigger refused a row while a write was being prepared or published, so nothing was committed and any canonical file already replaced was restored. With database_guard, a gbrain process wrote a row its publication does not own (another source, an unresolvable source, or a source checkpoint/topology change outside owner administration). This is a gbrain defect or a version mismatch between gbrain processes sharing the database, not a content conflict. The exception is relationship unreadable_state (#7636), message "writer state this database role cannot fully read (row-level security hides it or applies to the role, or a singleton row is missing)": the database role gbrain connects as cannot fully read the writer state the guard reads, because row-level security hides the persistence_brain or git_canonical_brain row or the source or page row the write names, or row-level security applies to sources at all (the Git-canonical recount refuses then, even under a policy that shows every row), or a persistence_brain / git_canonical_brain row is missing. The guard refuses instead of letting the write through as if the brain were unmanaged or the row absent. A derived-state maintainer trigger raises the same refusal (#7637, raiser gbrain_forget_page_retrievals, gbrain_queue_page_projection and the others listed in ENGINES.md) when row-level security applies to the role on a table it keeps up to date and the role holds no policy for it there, instead of leaving that derived state stale. The owner-only error_detail.state in gbrain sources writer status --probe --json names the table (persistence_brain, git_canonical_brain, sources, pages or, for the guest-source guard, guest_sources; #7780); the public receipt does not carry it. A write_error_detail.sqlstate of 42501 is a persistence protocol guard, not the managed-writer guard: see protocol guard. The receipt's write_error_detail names the table, operation, guard branch, source relationship and stage; it never contains page text or source names. For another trigger it also carries a closed reason: attribution_unclassified_table or trust_unclassified_table (a gbrain stamp trigger met a table it is not built for: a version mismatch), graduation_in_progress (the engine-graduation fence, SQLSTATE 55000, refuses writes until the move finishes: retry later), or unknown (an operator trigger gbrain does not know; its message text stays on the brain host). The same reason, raiser and table appear on the managed sync failure (gbrain doctor, the failure ledger) and in gbrain sync status --json last_error.write_error_detail. On the brain host run gbrain sources writer status --probe --json. Its recent_failures[].error_detail adds the source ids and the gbrain build and host that ran the attempt (attempt.consumer_version). If that build differs from gbrain --version, upgrade or restart every gbrain process that shares the database (serve, autopilot, sync jobs), then retry with a new request ID. If the builds match, report error_detail on the gbrain issue tracker. For relationship unreadable_state the build is not the cause, and the receipt's suggestion says so: run gbrain as a role that can read the table error_detail.state names (the table owner, a role that bypasses RLS, or a scoped role whose policies cover those rows, though protocol activation and a change to which sources are Git-canonical pass only the first two; see writer-protocol fences, and for a maintainer's table the policies a scoped writer needs), then retry with a new request ID; a missing row, which gbrain init never leaves, is reported like a defect. Never force-write, edit SQL or disable the guard.
database_guard with write_error_detail.sqlstate 42501 writer_upgrade_required, writer_not_quiesced, unsupported_mutation_protocol or writer_coordinator_required A persistence protocol guard (write_error_detail.raiser: gbrain_require_persistence_protocol, gbrain_guard_request_protocol, gbrain_guard_effect_protocol, gbrain_guard_protocol_activation or gbrain_guard_skill_publication) refused a row while a write was published, so nothing was committed (#7777). The error code is the guard's own: writer_upgrade_required (the gbrain process that ran the write does not declare the protocol the brain's floor requires: an older gbrain), writer_not_quiesced (shared skill publication is not active, or the canonical owner's protocol-2 capability changed after activation), unsupported_mutation_protocol (a request's target or protocol does not fit its operation), or writer_coordinator_required, either with relationship unreadable_state (the role gbrain connects as cannot read the persistence_brain writer state: row-level security hides it, or the row is missing; owner-only error_detail.state is persistence_brain) or without it (a shared-skill row outside the coordinated source capability). Only a guard's exact diagnostic, raised by that guard's own function, is typed; any other 42501 stays an ordinary permission error. Outside publication (write admission, protocol activation) the same refusal reaches the command as the database error itself, Error [database_error]: <code>: <diagnostic>, followed by the generic permission_denied grant advice; the code at the start of the message is the refusal. Follow the receipt's suggestion. unreadable_state: upgrading does not help; run gbrain as a role that can read persistence_brain (the table owner, a role that bypasses RLS, or a scoped role with a SELECT policy on it), then retry with a new request ID. Protocol activation, like a change to which sources are Git-canonical, passes only the table owner (without FORCE ROW LEVEL SECURITY) or a role that bypasses RLS. writer_upgrade_required: compare recent_failures[].error_detail.attempt.consumer_version from gbrain sources writer status --probe --json with gbrain --version, upgrade or restart every older gbrain process sharing the database, then retry with a new request ID; never lower the protocol floor. writer_not_quiesced: see writer_not_quiesced. unsupported_mutation_protocol and the skill-capability case: upgrade or restart older processes and submit again with a new request ID, and report error_detail on the gbrain issue tracker if the builds match. Never edit SQL or disable the guard.
ambiguous_source_path page_identity_changed A source registered at a Git subfolder <sub> has a page whose stored path <sub>/<file> could mean either <file> in the source directory (the older Git-root spelling) or <sub>/<file> inside a folder of the source that repeats its name, and both files exist. Sync refuses instead of guessing. See sources in a Git subfolder. Rename or move one of the two files, commit, then gbrain sync --source <source> --no-pull.
owner_marker_missing owner_marker_missing The ownership marker .gbrain-owner.json is gone from the checkout root while the reservation beside the checkout still names this owner and identifies this exact directory: device, inode and birth time all equal (a cleanup or a restore that dropped dotfiles). A directory the reservation does not identify exactly, a birth time within the 1 µs tolerance included, keeps the generic recovery_required and its recreated-root exit. No write publishes there, and a retry never brings the marker back, so the owner finishes each refused write failed (its outstanding-request slot is released); a sync stops blocked_by_failures on the refused file, without a hold. Re-create the marker with the verified self-transfer on the brain host: gbrain sources writer status --source <source> --json (note admin_state), then gbrain sources writer transfer prepare <source> --self-transfer --admin-intent writer_transfer_prepare --expected-state <admin_state>, then gbrain sources writer transfer accept <source> --path <root> --expected-epoch <epoch> --manifest <digest from prepare> --self-transfer --admin-intent writer_transfer_accept --expected-state <fresh admin_state>. Then run the same gbrain sync again. Never create or copy the marker by hand.
physical_root_device_changed recovery_required The checkout's filesystem device number changed while everything else matches, which macOS can do after a reboot. When the owner token, brain, worktree, root, inode and a non-zero birth time all match and the caller can verify database ownership, the write path re-stamps ownership by itself and the write proceeds. This refusal means the automatic re-stamp could not be verified; the suggestion says why. Do a deliberate self-transfer: gbrain sources writer status <source> (note admin_state), then gbrain sources writer transfer prepare <source> --self-transfer --admin-intent writer_transfer_prepare --expected-state <admin_state>, then gbrain sources writer transfer accept <source> --path <root> --expected-epoch <epoch> --manifest <digest from prepare> --self-transfer --admin-intent writer_transfer_accept --expected-state <fresh admin_state>. Retry the original write with the same request ID. Never delete ownership marker files.
physical_root_directory_changed recovery_required The directory at the checkout's recorded path is not the one the owner stamped: its inode changed, or its birth time differs from the stamp by more than 1 µs, while the owner token, brain, worktree, root and device all still match. A checkout deleted and recreated at the same path (restore from backup, rebuilt container, Migration Assistant copy) looks like this. A birth time within 1 µs of the stamp is accepted (#6501: APFS reports a new directory's birth time tens of nanoseconds apart across processes); a stamp of 0 against a filesystem that now reports a birth time, or a damaged stamp, still refuses. A refused page write carries detail: physical_root_directory_changed and this self-transfer as its fix (next: tell_user_to_run, both phases): an agent relays it and never runs it. If the checkout was recreated at its recorded path, do a deliberate relocated-root self-transfer: gbrain sources writer status <source> (note admin_state), then gbrain sources writer transfer prepare <source> --self-transfer --confirm-relocated-root --admin-intent writer_transfer_prepare --expected-state <admin_state>, then gbrain sources writer transfer accept <source> --path <root> --expected-epoch <epoch> --manifest <digest from prepare> --self-transfer --confirm-relocated-root --admin-intent writer_transfer_accept --expected-state <fresh admin_state>. writer status --json prints the commands filled in, and the refusal's fix is that prepare (with the accept as fix.then), a host-admin step (next: tell_user_to_run), on a write receipt too (#7671). Retry the original write with the same request ID. Never delete ownership marker files.
ownership_record_not_private recovery_required A private ownership record of the checkout (.gbrain-owner.json inside it, or .gbrain-owner-<hash>.json beside it) is readable by other users, typically after a recursive chmod of a copied brain, so it no longer proves who owns the checkout. Nothing was written; the message names no path. The refusal's fix is gbrain doctor --only foreign_ownership_marker on the brain host, which names each such record and the exact chmod 600 '<path>'. Run it, then submit the write again with a new request_id. Never remove the record.
recreated or moved canonical root recovery_required The checkout at the recorded path is a different directory (new inode and birth time after a restore, a rebuilt container or a Migration Assistant copy) or the recorded path now resolves through a symlink; without this release every verb, self-transfer included, refused with no exit (#5914). Same path, directory recreated: the self-transfer above with --confirm-relocated-root on both phases; it waives only the directory identity comparison and needs the reservation beside the root (.gbrain-owner-<hash>.json) and the stamp to agree on token, brain, worktree, root and coordination path. Recorded path now a symlink to the moved checkout: gbrain sources set-path <source> <path> on the owner host keeps the worktree and moves its records. Moved with no symlink: the refusal names it, see moved root. gbrain sources writer deactivate --dry-run lists physical_root when its real run would refuse, and the dry runs of gbrain sources remove, gbrain sources set-path, gbrain sources add and gbrain sources writer claim refuse with the same recovery_required their real runs would (#6849, #8625). Runbook: recreated root. Never delete ownership marker files.
physical_root_moved recovery_required The checkout was moved to a new path, or a parent folder of it was renamed, with no symlink left at the recorded path (#8625). The folder's ownership stamp names this brain, a worktree this host owns and a recorded root that no longer exists, and the reservation under the recorded name carries the stamp's token. gbrain sources add, gbrain sources set-path and gbrain sources writer claim, their --dry-run included, refuse with the recorded path, the worktree and its sources; nothing changed. A remote page write that reaches the automatic claim of such a folder carries only the detail, never a path or worktree id. The refusal's fix is ask_user (it moves the user's folders) and its verify is the same command with --dry-run. Worktree with sources: ln -s <new> <old>, gbrain sources set-path <source> <new>, rm <old>, then set-path for each further source. Source removed: mv <new> <old>, then gbrain sources add <id> --path <old> (--force for a plain directory), which reattaches the worktree; move it again with the first exit. A copy that is not the stamped directory (another filesystem, or copied and deleted) with its source removed cannot be moved back: restore the original from a backup, or switch to classic mode with gbrain sources writer deactivate --dry-run. A renamed parent folder is named and moved or symlinked instead of the checkout. Runbook: moved root. Never delete ownership marker files.
embedding_budget_below_worst_case embedding_budget_below_worst_case gbrain migrate embeddings (or the local migrate_embeddings operation) was given a --max-cost-usd cap below the migration's worst-case authorization: every planned provider request at its maximum input size, plus any debits a resumed run already holds. The run stopped before any provider request, re-chunk or vector invalidation, so nothing changed. The message and JSON carry cap_usd, worst_case_usd, debited_usd and required_cap_usd. Re-run with the value the suggestion names, for example gbrain migrate embeddings --to <provider:model> --dim <N> --max-cost-usd <required_cap_usd> --yes (operation: max_cost_usd). Preview first with --dry-run, which prints the worst-case authorization beside the estimate. Requests settle to reported usage, so actual spend is usually far below the cap. See embedding migration.
frontmatter slug conflict frontmatter_slug_conflict (invalid_params on a gbrain older than v0.60.47.0) A file's frontmatter slug: names a different page than its path. On a write nothing is written; during sync the file is held and the rest of the source imports. Remove the slug: line or make it match the path, commit, then sync. See frontmatter_slug_conflict.
cursor_processing_options_conflict invalid_params Retired in 0.60.255.0 (#6712): no longer returned. An unfinished sync's processing opt-outs (--no-embed, --no-extract, --no-schema-pack) are inherited by every run that resumes it, and the result names them in inherited_options. An older gbrain still returns it when a run's processing flags conflict with the cursor's. On an older gbrain, run the printed resume command (gbrain sync --source <source> --no-pull plus the saved flags) or drop the conflicting flag. After upgrading, rerun the sync: it finishes the cursor with its stored opt-outs.
take_row_collision take_row_collision A save adds a takes-table row whose row number already belongs to a different take that exists only in the database. The save stops instead of overwriting that take. Renumber the new takes row, or add the existing take to the page's takes table, then save with the current expected_revision and a new request ID (the content changed).
invalid_source_uri invalid_source_uri The brain has shared skillpacks, and the page's stored source_uri is a file: URI that cannot be turned into a local path, so gbrain cannot prove the write stays outside a skillpack. Shared-skill protection stays on. The source owner inspects the page's stored source_uri on the brain host and replaces it with an absolute file URI or clears it; there is no dedicated command yet. Retry with a new request ID.
queue_capacity queue_capacity Admission would exceed a write-journal limit. Existing requests keep their place; nothing is evicted. For the cumulative limits (lifetime request IDs and receipt bytes), detail names the limit, for example principal_lifetime_ids; for the outstanding-request caps, detail carries the counts (outstanding=<used> limit=<limit>), the message names the source holding the most of the local CLI principal's slots, and a managed gbrain sync drain waits them out (write_capacity). At the shared local CLI principal's outstanding cap, a page or sync write from a source holding less than its fair share (the cap divided by the sources holding outstanding requests on it) is still admitted, a sync publication group whole, so a source passes its share by at most one group; the brain cap stays hard. Gates that read the principal's headroom before admission (maintenance backpressure, purge deferral, topology lifecycle checks) still count every source's requests. For a cumulative limit, run the printed gbrain config set persistence.limits.<limit> <value> (sized for about one more year at the current rate), then retry with the same request ID. For outstanding-request, queued-byte or recovery-byte limits, let outstanding requests finish and check gbrain sources writer status. See bounded admission and retention.
index_building, index_missing or indexes_valid checkpoint_validation_timeout A managed sync's checkpoint validation (the check that every page receipt of the run committed) hit the coordinator's 5-second statement timeout on a large persistence_requests table. The checkpoint request failed terminally instead of being retried ahead of every other write to the source, so other writes proceed; last_commit is unchanged and every page the run already committed stays committed. detail says which of three states the request indexes were in when the hint was built. index_building: migration 179 is still building the indexes; wait (doctor persistence_request_indexes shows progress), then run the printed retry. index_missing: run gbrain repair request-indexes --apply (it drops an INVALID index and rebuilds it concurrently on Postgres), then the printed retry. indexes_valid: run the printed retry once; if it times out again, report the request id with the persistence_request_indexes and persistence_request_growth entries of gbrain doctor --json. The retry is gbrain sync --source <source> --no-pull plus the run's --repo base and cursor options (--full, --working-tree, --src-subpath, --exclude, --include-hidden, --strategy) and saved processing flags, so it resumes the same cursor. Do not cancel the request: a cancelled checkpoint still blocks the next one.
account_changed, account_unresolved connector_account_changed A managed Google, GitHub, meetings or Slack connector's credential resolves to a different account than the one pinned for the source (Google email, GitHub App installation or login, meetings provider user, Slack workspace), or to no account at all. Google checks every enabled service before any service runs. Nothing was imported. No reset flag authorizes an account change. The suggestion gives two branches with real values. (A) Restore the credential for the pinned account (the configured g_token_env, g_token_command, vault credential, gh_token_env or GitHub App key; for meetings and Slack, the key saved with gbrain connectors auth <provider> --token - or the configured m_token_env / s_token_env), then gbrain sync --source <source>. (B) For a deliberate change, add a new source for the new account (gbrain google setup --account <email>, gbrain sources add <new-id> --kind github … --app-install <id>, gbrain sources add <new-id> --kind meetings --provider <provider> or gbrain sources add <new-id> --kind slack --channels <ids>), then gbrain sources archive <source>; existing pages stay under the old source. The refused run is recorded, and autopilot then skips the source (an unavailable-path skip in the fan-out, freshness_source_path_skipped with code: connector_account_changed in the freshness loop) instead of retrying it every interval; doctor connector_account_mismatch lists such sources. A gbrain sync --source <source> that passes the account check clears the skip, and so does a change to the source's connector config (one more automatic try).
pre_upgrade connector_intent_outdated A connector write was admitted in the intent format retired in v0.60.11.0. With detail pre_upgrade it was admitted before this brain's upgrade; otherwise a connector host older than v0.60.11.0 admitted it. The consumer recovers any file publication in progress first, then fails the request. pre_upgrade: nothing to do; the item is fetched again on the next gbrain sync --source <source> under a new request ID. Otherwise: gbrain upgrade on the host that runs connector jobs, then gbrain sync --source <source>.
invalid_connector_text invalid_connector_text A Google or GitHub item's identity field (a path, item id or account) contains a NUL or an unpaired UTF-16 surrogate, which cannot be stored. Prose (bodies, subjects, titles) is cleaned at render time and never refused. The item is counted toward a hold; the rest of the sync continues. Nothing to run for one refusal. Once the item is held, gbrain sources status <source> names it; after the provider data is fixed, gbrain sources retry-held <source>, then gbrain sync --source <source>.
connector_holds_exhausted connector_holds_exhausted A Google or GitHub source already holds 100 items and this sync would hold another. The sync stopped without advancing its cursor. So many held items usually means a source-wide problem (a broken renderer, a revoked scope), not bad items. gbrain sources status <source> to see the held items and their error codes, fix the cause, then gbrain sources retry-held <source> and gbrain sync --source <source>. gbrain sync --source <source> --full also clears every hold.
fence_not_carried connector_fence_below_timeline A managed connector re-render would have dropped a facts or takes fence the stored page keeps below its timeline sentinel, or one that is duplicated, unbalanced or unparseable. The write was refused so those rows are not expired; the item is counted toward a hold. Preview gbrain repair connector-fences --source <source>, apply it after review with --apply, then gbrain sources retry-held <source>. A page the repair counts as ambiguous needs a manual edit (see repair).
consumer_upgrade_required unsupported_mutation_protocol A connector on v0.60.11.0 or later sent a connector_v2_* write to a persistence consumer older than v0.60.11.0, which does not know the format. Other permission_denied refusals on connector receipts are never relabeled as upgrades. gbrain upgrade on every consumer and worktree-owner host, then gbrain sync --source <source>. Upgrade those hosts before connector hosts.
recovery_version_unsupported recovery_version_unsupported (effect error_code; head blocker state) A publication or withdrawal-mirror recovery record on the source's worktree has a version this gbrain does not know: a newer gbrain wrote it. Recovery refused before reading it, so the record, its staged files and the canonical file are exactly as they were; the effect keeps retrying (it never parks) and writes on that worktree wait for it. gbrain sources writer status and a stalled sync name it (effect_recovery or request_recovery with this state) as needing intervention. v0.60.290.0 and older predate this check: they read a version 2 withdrawal-mirror record as version 1 and fail every attempt with effect_unavailable (an untyped TypeError) instead, without deleting the record or its staging file. fix.next is tell_user_to_run gbrain upgrade: upgrade gbrain on the host that owns the source's canonical worktree and restart its serve, sync and worker processes; the upgraded writer finishes the recovery. Verify with gbrain sources writer status --source <source> --json. Never delete the record or its staged files, and never transfer the source to an older host to force it through.
segmented_mirror_writer_gate effect error_code, then the parked target's code (targets_parked) A withdrawal (forget, forget_fact, purge_fact) on a page stored in segments committed, but a gbrain older than the segmented writer floor that doctor segmented_storage still warns about wrote to the brain in the last 7 days: another host, an older serve or worker still running on this host, or an older write this build has not matched (doctor names the host and when the hold clears). This host's own writes from before it upgraded, once the upgraded build has made the same kind of write after them (doctor's information case), keep pages.segmented_storage off but do not hold the mirror. Its mirror would write a version 2 recovery record that gbrain cannot read (v0.60.290.0 wedges the worktree on it, see recovery_version_unsupported), so it wrote nothing: the canonical file keeps the withdrawn row, the withdrawal's Git effect waits, and the mirror retries and parks after five attempts like any failed target, so writes on the worktree go on. The refusal names each older host with its version, the kind of write and when it was last seen. fix.next is tell_user_to_run gbrain upgrade on the named hosts (and a restart of their serve, sync or worker processes). Once those hosts are upgraded and their older writes are 7 days old, the owner retries the parked mirror by itself (checked at most once a minute); the file loses the row and the Git effect commits it. gbrain sources writer retry-effects <source> --request-id <request> retries it sooner; it parks again while the hold lasts.
unbound_source owner_unavailable (remember: unavailable with write_error: owner_unavailable) On Postgres, a page write or a remember about an existing page went to a source that has a checkout path but no canonical owner. It is refused by default because another host may own the files. The same reason appears when the source was bound, or the page gained a canonical file, after a database-only write was accepted, and (as a source_changed sync failure) when a canonical file appears at the path of a page written while the source was unbound. Classic mode: write the file, commit, gbrain sync --source <source> (a remote agent asks the user to). Otherwise bind the source (gbrain sources writer status <source> --json, then gbrain sources writer claim <source> --path <checkout> --admin-intent writer_claim --expected-state <admin_state>), or opt in with gbrain config set persistence.unbound_write database_only. Not retryable. See unbound sources on Postgres.
disabled_by_config owner_unavailable (gbrain import on a managed brain) sync.write_through is off, so a page write records no canonical worktree, and a managed import publishes only through the source's canonical owner. The import refuses once, before it admits any file, and spends no write capacity. Copy the files into the source's checkout, commit them, then run gbrain sync --source <id>.
zero_norm, non_finite or empty_input embedding_zero_norm The embedding provider returned a vector with no direction (all zeros, NaN or infinity) for a chunk, or the chunk text was empty. A vector index silently skips such a row, so gbrain refuses to store it. Only that chunk is refused: the page text and every other chunk's vector are saved, and the page is left for gbrain embed --stale. It is never retried as a rate limit or network error. Inspect the named page's chunk text (empty, whitespace- or symbol-only chunks are the usual cause) or the embedding provider, fix it, then run gbrain embed <slug> (add --source <source> for a non-default source). If normal text also returns zero vectors, the provider or model is broken; check it with gbrain doctor.
targets_parked (doctor: parked_effects) effect error_code A Git backup or withdrawal target failed five times in a row and was set aside so the other pages keep committing. An effect error_code of git_index_stale means an index lock older than 10 minutes blocks the checkout: .git/index.lock in it (git -C <checkout> rev-parse --git-path index.lock for a linked worktree). The canonical writer removes such a lock by itself when it can prove no process holds it and no git runs in that checkout, and then retries the effects it parked; the error's fix says why it could not prove that (another platform, a container, a network filesystem, or a live git). Otherwise remove it only if no git command is running there, then run the retry-effects command. A fresher lock (git_index_locked) is retried as contention and never parks. An effect error_code of git_target_pending means Git still lists a removed page file in the index (on Windows, a program such as a sync watcher, an indexer or antivirus may still hold it open): close that program, check with git -c core.fscache=false status on the brain host, then run the retry-effects command. It is retried 30 seconds apart and parks after five attempts like other target failures. The page write itself committed; its Git backup or withdrawal is incomplete. Contention, dependency waits, shutdown and transient database errors never count toward the five. gbrain sources writer status <source>, fix the cause it names, preview with gbrain sources writer retry-effects <source> --request-id <id> --dry-run, then run it without --dry-run. Each run grants one more attempt per parked target; a target that fails again parks again. A target no retry can move (declared db_only since, or left in a former canonical worktree) is settled on proof instead.
writer_admin_locked writer_admin_locked The operator set the brain's writer admin lock (gbrain sources writer lock), so writer claim, activate, transfer prepare and transfer accept refuse for every caller. Ordinary writes are not affected. Agents: stop and ask the operator; do not unlock it yourself. The operator runs, on the brain host, gbrain sources writer unlock, re-reads gbrain sources writer status <source> --json, administers, then gbrain sources writer lock again. See the writer admin lock.
writer_not_quiesced writer_not_quiesced Activation found an older writer, a legacy lock, or queued, running or recovering work. When work blocks it, the message names the blocking effect id, kind, source, page and request id. Stop the writers named in the claim and activate runbook, inspect the named work with gbrain sources writer status <source> --json, let it finish, then retry. A committed write whose embedding effect is stuck queued or failed is settled by gbrain repair embedding-effects --source <source> (preview), then the same command with --apply; see stale queued embedding effects.
source_path_missing source_changed gbrain sources writer activate (with or without --dry-run) found a source whose recorded local_path no longer exists on this host, for example a checkout that lived in a temporary directory. Activation cannot verify that source's canonical directory, so nothing changed. The message names the source and the missing path. Claiming the source at another directory does not help while the stale path stays recorded. Run the command the suggestion prints: gbrain sources set-path <source> <directory> to point the source at its checkout (the suggestion fills in the claimed directory when the source is claimed), or gbrain sources remove <source> --confirm-destructive when the source is no longer needed (gbrain sources archive <source> keeps a 72-hour grace period). Then gbrain sources writer activate --confirm-quiesced --dry-run and activate.
canonical checkout missing recovery_required A page write (put_page, capture, add_timeline_entry, edit_page and the other page writers; detail: source_checkout_missing) found that the source's canonical checkout directory does not exist on this host, for example a brain copied to another machine or container without its source directories; nothing was written, and the message names the source but not the path. A source directory missing inside a checkout that exists (Git keeps no empty directory, so a fresh clone lacks an empty member folder) is not this refusal: the write creates it. A managed source lifecycle command (gbrain sources archive, remove, purge, restore, rebind) found that the source's canonical checkout directory was deleted out of band. When the directory a rebind names holds that checkout's ownership stamp (it was moved, not deleted), the refusal is physical_root_moved instead, and gbrain sources set-path --dry-run refuses the same way as the real run. A source with no pages that is the only source on that checkout is retired anyway: archive, remove and purge succeed and the receipt records retired_without_checkout with the missing path. Otherwise nothing changed; the message names the path, the page count and how many other sources share the checkout. Recreating an empty directory at the same path does not help (its physical identity differs). Restore the checkout (for example from a backup) and retry; gbrain sources writer status --source <source> --json shows the registered path. If it is gone for good, switch the brain to classic mode with gbrain sources writer deactivate --dry-run, then the printed apply_command (see the deactivate runbook), and retire the source there with gbrain sources archive <source>.
migrations_running migrations_running (exit 75) gbrain apply-migrations (or the post-upgrade step of gbrain upgrade) found another runner holding the brain's orchestration lock and stopped before touching the migration ledger, so migrations never run twice in parallel. The message names the holder's host and pid. A holder that died is taken over automatically on the next run. gbrain upgrade reports this as Migrations: running, not as a failed upgrade. Wait for the other run to finish; gbrain doctor shows migration progress. Then gbrain apply-migrations --yes confirms everything is applied.
schema_behind migrations_pending (reason schema_behind) A managed write (put_page and every write admitted the same way) was refused before admission because the brain schema is at a lower version than this gbrain build needs: an upgrade installed the new binary but gbrain apply-migrations did not finish, often because the database role gbrain connects as does not own the tables. The write path reads tables or columns only the pending migrations add, so publishing now would fail. It is not retryable as is (class caller): the same write refuses until the schema is migrated. Nothing was admitted and the request id was not used. A replay of a request id accepted earlier still reconciles, and the apply-migrations orchestrators are not refused while they hold the migration lock. Run gbrain apply-migrations --yes on the brain host as the database role that owns the gbrain tables (the fix renders tell_user_to_run when this connection's role does not own them), confirm with gbrain doctor --json (schema_version at head), then resubmit the same write: the same request id commits. A write that already failed on a missing column or table is classified schema_missing by gbrain write-request <request_id> --json.
writer_deactivate blockers writer_not_quiesced, writer_admin_locked, writer_admin_state_changed, writer_lock_unavailable gbrain sources writer deactivate found pending work (a queued, running or recovering write, a topology change or effect that is not settled, a held connector item, or a live connector or maintenance lease), the writer admin lock, a changed admin state, or a local process holding a worktree lock. Nothing changed. The suggestion names each blocker and its exit. Run gbrain sources writer deactivate --dry-run for the full list, run each named exit (gbrain cancel-write-request <request_id>, gbrain sync --source <id> --no-pull, gbrain repair embedding-effects --source <id>, gbrain sources writer retry-effects <source> --request-id <id> --dry-run, gbrain sources writer unlock, gbrain sources retry-held <id>), then deactivate again with a fresh --expected-state from gbrain sources writer status --json. See the deactivate runbook.
timeline extract refused the printed code, usually writer_coordinator_required gbrain extract timeline --source db (or a timeline-only gbrain extract timeline on a managed brain) could not write a page's timeline rows. It prints refused: <code>; nothing written; existing timeline rows are untouched per page, a summary of written versus refused, and exits 1. The rows import already stored for each page stay as they were. gbrain extract --stale (add --source-id <id> when you scoped the run) publishes links and missing timeline rows on the managed path. If it refuses too, follow the row for the printed code.
unknown option (repair) invalid_params gbrain repair refuses any option it does not list, so a mistyped flag or --max-usd never runs a repair silently without it. Fix the option (gbrain repair --help). To cap paid repair work, preview with gbrain doctor --remediation-plan --json and, after the user agrees, run gbrain doctor --remediate --yes --include-repairs --expect <plan_hash> --max-usd <n>.
colon_slug_windows_write_through colon_slug_windows_write_through A page slug such as calendar:abc is valid, but its canonical file name would contain :, which Windows cannot store (it names an alternate data stream). On Windows, a write that would publish that file is refused before admission, and gbrain sync skips each such file with this reason instead of failing the run. Database-only writes of the same slug (no repo configured, sync.write_through off, an unbound source, or a read-only mirror source and pages created while it was one) still succeed, and macOS and Linux are not affected. Use a slug without : (the suggestion names one), or write the page from a macOS or Linux host that owns the source. For a skipped sync file, rename it without : on a macOS or Linux checkout, commit, then run gbrain sync --source <source> --no-pull on the Windows host.
embedding_auth_failed embedding_auth_failed The embedding provider rejected the configured key (HTTP 401 or 403). Printed once per process on stderr, naming the key source in effect: an environment variable (for example OPENAI_API_KEY, which wins over the config key) or the config key in ~/.gbrain/config.json. No key or part of one is printed. Environment key in effect but the config key is right: remove the variable from the environment of the process that reported it (shell profile, ~/.gbrain/.env, or a daemon's service definition) and restart that process. Environment key intended: replace it with a valid key, restart, and run gbrain config unset openai_api_key (or the matching key). Config key in effect: gbrain config set openai_api_key <valid key>. Then gbrain embed --stale embeds what was saved meanwhile. gbrain doctor (embedding_key_source) shows the key source in doctor's own environment.
managed_pull_skipped (cycle warn); doctor sync_freshness "upstream unknown" or "upstream N commit(s) ahead" managed_pull_skipped A managed brain never runs git pull inside a cycle: Git pull needs an explicit drained maintenance window, so an explicit gbrain sync without --no-pull is refused with writer_coordinator_required. An unattended cycle asked to pull (autopilot passes pull: true, gbrain dream --pull) instead syncs the checkout as it is and reports it: the sync phase result carries details.upstream_refresh (pulled, failed, skipped_managed or not_requested), and when the checkout tracks an upstream the phase is warn with details.warning (code, cause, fix, docs). Every sync also records the checkout's last upstream observation (the upstream commit, when it was last fetched or pushed, and how many upstream commits the synced commit lacks) in the source row. Doctor sync_freshness reports that separately from the local projection: a source with a remote_url whose observation is missing or older than 24 hours is "upstream unknown", and any source whose observation saw upstream commits it has not synced is "behind"; neither is reported fresh. details.upstream_unknown_count and details.upstream_behind_count count them. gbrain sources refresh <source> (the printed fix fills in the source). It drains writes to the source's checkout, fast-forwards it to its upstream and runs the managed sync for every source bound to that checkout; see worktree refresh refusals for what it can refuse. On a brain that is not managed, gbrain sync --source <source> pulls and records the observation.
managed_sync_flag_refused (detail = the flag) managed_sync_flag_refused A managed source keeps every failed-receipt and ignored-file guard, so gbrain sync --skip-failed and gbrain sync --include-gitignored have no managed meaning. A strict (git-canonical, config.canonical = "git") source also refuses gbrain sync --working-tree, because it indexes committed bytes only; that refusal comes from the managed-sync guard, which reads the source row. The refusal names the flag and comes before anything runs: at parse in gbrain sync (before a legacy ledger row is acknowledged or the cost gate runs, --all included), before the serve-delegation ladder looks for the serve's socket, and in the managed-sync guard that sync jobs, MCP sync_brain and the cycle reach. Nothing is admitted and no cursor is written. Rerun the printed fix (the same command without the flag). A failed file is fixed and then retried by the plain gbrain sync --source <source> --no-pull; an ignored file syncs once it is committed and not ignored, and an edit on a strict source syncs once it is committed (gbrain git commit-push). gbrain sync status --source <source> --json shows the source's failures and holds.
facts_absorb_write_refused (<code>); ingest_log write_refused: <code> … facts_absorb_write_refused A durable facts-absorb job extracted facts but the write path refused to store them, for example writer_coordinator_required because the entity's Markdown file sits in a claimed canonical worktree before sources writer activate, or permission_denied, invalid_params or writer_registration_required. These refusals do not change on retry, so the job goes straight to dead on its first attempt instead of re-running inference; on a brain that is not yet activated, a job whose source root is a claimed worktree is refused before extraction starts, so it makes no model call; the facts:absorb row in ingest_log (and doctor facts_extraction_health) records write_refused with the real code, not a provider failure. Two outcomes are not refusals and are logged under their own reasons, which doctor never counts toward its threshold: write_pending_accepted, a facts write that was accepted and whose receipt is still queued, running or recovering when the job stopped waiting (the job waits up to 30 s, bounded by its deadline; the write commits later), and write_deferred_unadmitted, a canonical writer that was busy before anything was admitted (writer_lock_unavailable, no receipt; the job retries). Doctor warns about deferrals only when they persist (see the check's gbrain sources writer status fix). Doctor's incident count is a historical metric: it counts the facts:absorb rows of a rolling 24 h window, says when they age out, and keeps counting them after the cause is fixed and the job retried, so a warning there does not by itself mean anything is still broken; the threshold (facts.absorb_warn_threshold) is unchanged. The current state is the check's jobs still dead count: facts-absorb jobs that went dead or failed in the last 24 h and that no later job for the same page completed after, each named with gbrain jobs retry <id>. The source page itself was already saved. Fix the named cause first: gbrain sources writer status <source>, then finish the claim and activate runbook for a claimed worktree, or fix the grant. Then gbrain jobs retry <job id> (the error names the id).
no_context_ceiling no_context_ceiling A queued job under a cost cap you set stopped before a provider call: the model has a registered price, but gbrain knows no context-token ceiling for it, so it cannot reserve the most one call could cost. OpenRouter models hit this, because that provider declares no context window per model. The message names the model, and the JSON fix asks you before it reruns the command without your cap. Re-registering the price does not help. Choose one. Rerun the command without your cap (the fix command, which replaces --max-usd with --yes): the default cap applies and this model runs unmetered with a warning. Or keep your cap: look up the model's context window on the provider's model page (OpenRouter lists it as context_length) and give it to the brain-host operator. gbrain jobs list --group <id> --json shows the stopped job.
no_pricing no_pricing A cost cap you set (--max-cost, --max-usd, --max-cost-usd, or an explicit cap in config such as cycle.extract_atoms.budget_usd) cannot be enforced, because gbrain has no price for the model the run was about to call. The run stops before that call. Under a default cap an unpriced model warns and runs instead. The message names the model, provider and kind, and JSON output carries the same guidance as fields: code, model, provider, kind, units, lookup, register_command, register_scope and docs. Look up the provider's current price for the model, for example by searching the web for its pricing page. A chat model needs USD per 1M input tokens and USD per 1M output tokens; an embedding or reranker model needs USD per 1M tokens. On the brain host, run gbrain pricing set <model> --input <usd> --output <usd> --source <pricing-page-url> (or --rate <usd>), then retry. An agent connected over MCP cannot register prices: give the command to the brain's operator. See registering a model price.
raw upload on a managed brain writer_coordinator_required gbrain files upload-raw of a small (git-storage) file whose .raw/ destination is inside a managed canonical worktree. The persistence coordinator does not publish raw files yet, so the worktree refuses writes from outside it; starting a gbrain serve owner does not change that. The refusal comes before anything is created: no .raw/ directory and no files row. With no storage backend, file_upload for such a page no longer suggests upload-raw. An object-storage upload (a media file, or 100 MB and over) of a file inside a managed worktree is refused the same way, because its .redirect.yaml pointer would be written beside the file: the refusal comes before the upload, so nothing reaches the backend. Configure storage (supabase, s3 or local) in the gbrain config, then run the printed gbrain files upload <file> --page <slug>; for the pointer refusal, run the printed upload-raw … --no-pointer, which uploads the file and records it for the page without a pointer. Check either with gbrain files list <slug>.
readable_by_invalid readable_by_invalid A remote write (MCP over HTTP or stdio) set frontmatter readable_by to a value that names no valid reader (an entry that is not a member id or group:<id>, an empty list, a non-string), removed readable_by from a page that names readers, or set readers that leave the page unreadable by the writing connection's member. The message names the bad entry; nothing was written. A webhook capture (POST /ingest with X-Gbrain-Slug, then its ingest_capture job) follows the same rule for the token or OAuth client that sent it: the route answers 403 readable_by_invalid and queues nothing, and a queued job whose page gained readers before it ran refuses at write time (GST-2112). Write the field as a list of member ids and group:<id> entries, for example readable_by: [alice-example, group:team-a], keep your own member or group in it, and submit again with a new request_id. To widen or hand a page to other readers only, ask the user to change it on the brain host.
timeline_rows_would_be_removed timeline_rows_would_be_removed A remote put_page (or a put_pages entry) has no Timeline section at all — no <!-- timeline --> sentinel and no ## Timeline or ## History heading — and would delete dated entries the page has, including rows add_timeline_entry added. put_page content replaces the whole page, so the omission must be explicit. Nothing was written. A section that is present but empty is a deliberate delete and is not refused; a local gbrain put without --expected-revision keeps the rows instead. Re-read with get_page include_content:true, keep the Timeline section and resubmit with a new request_id; to remove every dated entry on purpose, resubmit the same content with drop_timeline: true (on put_pages, per entry). A successful write that deletes rows reports timeline_rows_removed {count, earliest, latest, warning, fix} (dates only); get_versions then revert_version restores them as new rows.
purge_lookup_timeout purge_lookup_timeout A page purge (gbrain delete <slug> --purge) ran one of the journal lookups that still execute inside its publication transaction (the lookup of stored intents for the slug, the re-check of requests admitted after its preparation scan or pending at that scan, the locking read of the requests to redact) and that statement hit the transaction's 5-second statement budget on a large persistence_requests table. The request failed terminally instead of being released as database_contention and claimed again: nothing of the page was removed or tombstoned, nothing in the journal was redacted, and later writes to the source move again. Do not assume the requested content was erased. The substring search for the page's claims no longer runs here: it runs at preparation in bounded keyset chunks under the preparation budget, and a sweep that outruns that budget twice ends preparation_stalled instead. A committed purge's receipt reports journal_sweep (scanned, ceiling, tail, pending_rechecked, complete); complete: false means a cap was hit (the 10,000-match cap or the tail bound) and some requests were not tested. If the receipt says the slug index persistence_requests_slug_intent is missing or INVALID, run gbrain repair request-indexes --apply (the persistence_request_slug_intent_index migration builds it online; the index serves the slug lookup, not the substring sweep), then submit the purge again with a new request_id. Otherwise submit it again with a new request_id (a retry with the same id returns this failure); if it times out again, report the request id with the persistence_request_indexes and persistence_request_growth entries of gbrain doctor --json.
purge_mirror_unwritable purge_mirror_unwritable A fact or page purge appends a text-free intent line to the purge mirror (<brain home>/.gbrain/purge-events.jsonl) and fsyncs it before it commits, so a later restore of an older backup can replay the purge. The mirror could not be written (a directory in its place, a read-only home, a full disk), so the purge was refused: nothing was removed, tombstoned or redacted. 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.
purge_replay_incomplete purge_replay_incomplete A restore replays every purge newer than the backup, and each replayed page purge sweeps what the live purge swept, the stored requests that carry the page included. The replay of the named purge could not cover every such request, so the restore stopped: that purge was not replayed and nothing was restored. A restore never reports a partial sweep as replayed. Do not use the restored copy. Report the purge request named in the message with the output of gbrain doctor --json, then restore again once it is fixed.
preparation_stalled preparation_stalled The write's owner could not finish preparing it. Every write has a preparation budget (persistence.sync_preparation_ms for a managed sync member, persistence.maintenance_preparation_ms for every other managed kind, 120 s each; remember, put_page and edit_page keep 30 s), the owner releases the claim at the budget and tries again, and a request cut off persistence.max_preparation_attempts times (default 2; a process killed mid-preparation counts too) is finished failed with this code instead of being claimed again and holding the rest of its root. The receipt names the last recorded step and what it was waiting on (git, fs, db, pool or unknown); while the write was still running, gbrain sources writer status --json showed the same on claim.stall (preparation_overdue). The rest of the root keeps publishing. A managed sync member (an import, delete or rename of a file) is also held: the sync turns the failed receipt into a preparation_stalled hold and carries on, so the file is not imported until it is retried. The file is fine; this is the write owner stalling (a database or pool wait, a hung step), never a frontmatter or fence problem, so no repair applies. The hold's message names the request and the step; a held deletion keeps its page. A stalled hold re-screens by itself only when the gbrain version changes; a run that stalls many files in a row stops with preparation_systemic instead of holding them all. A foreground write (put_page, edit_page, remember) or a maintenance write (fact-fence adoption, maintenance page writes) gets the terminal receipt only. The deadlines sit behind persistence.preparation_deadlines (false restores the old behaviour, where only remember, put_page and edit_page had a 30 s budget). Run gbrain sources writer status --source <source> --json (read-only: the step, its wait cause, the owner process and its gbrain version), fix what it names (restart or upgrade an owner that predates deadlines, free the pool, let the lock holder finish), then for a sync hold run gbrain sources retry-held <source> and the same gbrain sync with the same options (the hold's fix.then.then and retry-held print it, for example gbrain sync --source <source> --no-pull --no-embed). When that sync still has a backlog to finish, it finishes it first and re-screens the scheduled files in the same invocation (the drain yields at the checkpoint and discovers again), so one run of the printed command clears the hold. A foreground write needs a new request_id; the next maintenance run submits its write again. Runbook: catch-up stuck / held N files.
file_unreadable (sync hold) file_unreadable A managed sync held one file because it is not a readable regular file inside the source root: a symlink (to a file outside the root or inside it), a non-regular file, or a permission or loop error. Sync never reads or follows it. Until GBRA-130 the whole sync stopped at that file on every run and the rest of the source never imported; now only the file waits. A source root that is itself replaced by a symlink still refuses the whole sync. Make the file a readable regular file in the checkout (replace the symlink with the file, fix its permissions) or exclude it with sync.exclude, and commit. A commit that changes it re-screens the hold on the next sync; after a permission fix run gbrain sources retry-held <source>, then the same sync.
page_write_failed (sync hold) page_write_failed A managed sync held one file because its write failed the same way three times (the same code, origin, error class and SQLSTATE in this source), with an error gbrain cannot classify: an owner exception (for example Postgres 54000 when a frontmatter tag is too long for its index), or a refusal the receipt does not explain. Until GBRA-130 every sync stopped blocked_by_failures at that file and the rest of the source never imported; now the file is held and the rest of the source syncs. The first two failures still stop the run, so a one-off defect never holds a file. Read the receipt the hold names (gbrain write-request <request_id>, read-only). Fix the file when the error names its content (shorten the tag, split the page), or report the receipt with the gbrain version. Then gbrain sources retry-held <source> and the same sync. An upgrade re-tests the file on its own. A hold whose meta.write_failure.origin is freeze (GBRA-133) is different: sync could not even prepare the file (an unexpected error while reading or screening it, before any request was admitted), so it holds it on the first failure and names the error in the hold message; the next syncs re-test it on their own until it has been held 3 times, so a transient fault clears without help. When most files of one run fail that way the run stops instead (the cause is not the files).
content_null_bytes (sync hold) content_null_bytes A managed sync held one Markdown file because its text holds NUL bytes (U+0000). Page text is stored as UTF-8 without NUL bytes. The usual cause is a UTF-16 file (a Windows "Unicode" save; the hold says so when the file starts with a UTF-16 byte order mark), a binary file named .md or a crash-padded file. Until GBRA-133 the whole managed sync stopped at that file on every run (storage_error, SQLSTATE 22P05) and the rest of the source never imported; now only the file waits. With sync.holds=fail the run stops with content_null_bytes instead of holding. 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 gbrain sync --source <source> --no-pull. The hold re-screens when the file changes.
content_filter_owned (sync hold) content_filter_owned A managed sync held one committed file because Git stores it through a filter: its path has a filter attribute at the synced commit naming a clean/smudge driver (whether or not this checkout's Git config defines it, since the commit may have been cleaned on another machine), or its bytes start with git-crypt's header. The committed bytes are what the filter's clean program wrote (git-crypt ciphertext, for one), not the text in your checkout, and gbrain does not run a repository's filter programs during sync, so it cannot turn them into text. Sync reads the attribute at the synced commit with git check-attr --source (git 2.40 or newer) or, on an older git, from a temporary index of that commit with check-attr --cached. Those reads run with fsmonitor, hooks and every Git transport switched off and with lazy fetching off, so reading the attribute runs no repository program and fetches nothing; when a partial clone lacks a .gitattributes that applies to the file, the file is held git_object_missing instead. Every other Git read of a managed sync fetches nothing either (see git_object_missing). A plain-text file under a filter attribute nobody uses is held too: the hold is the safe side and loses nothing. Before, a filtered file imported its stored bytes as the page text, and a git-crypt file was held content_null_bytes. A page imported from such a file before this release is left as it is until the file changes. Git LFS pointers are not this hold. With sync.holds=fail, and on a company-brain source, the run stops with content_filter_owned instead of holding. Leave the file out with sync.exclude, or commit it without the filter so Git stores its text, then gbrain sync --source <source> --no-pull. The hold re-screens when the file changes. For a plain-text file under a filter attribute nobody uses, remove the attribute from .gitattributes, commit, and run gbrain sources retry-held <source>: a commit that changes only .gitattributes does not re-screen the file.
git_object_missing (sync hold) git_object_missing A managed sync held one committed file because the commit names a Git object the checkout no longer has (an interrupted git gc, a partial clone without its promisor remote, disk corruption) and the working-tree copy differs from it or is gone, or because a partial clone lacks a .gitattributes that applies to the file at that commit, so sync cannot read whether a Git filter owns it (sync fetches nothing to find out). When the working-tree bytes hash to the committed blob id, sync imports them and holds nothing. A managed sync never fetches a missing object: every Git read it makes runs with Git's transports and lazy fetching switched off, so in a partial clone (git clone --filter) a blob the clone never fetched fails the read and the hold names the partial clone. A blobless clone with a normal checkout syncs as usual, because checking out fetched every file it holds; a partial clone with no checkout (--no-checkout) holds every committed file. When rename detection needs an older blob the partial clone lacks, the sync compares the whole tree instead, so the new path imports as a new page and the old page is deleted. A treeless clone (git clone --filter=tree:0) that lacks a tree of the commit being synced cannot list that commit's files, so the run stops with git_object_missing instead of holding: nothing is synced and no page is deleted. Git 2.40 to 2.44 ignore Git's switch for lazy fetching, and the transports being off stops the fetch there, with the same result. Until GBRA-133 the whole managed sync stopped at that file on every run. In a partial clone, fetch the blob the hold names with git cat-file -p <blob> in the checkout (or check the file out), then gbrain sync --source <source> --no-pull. When the run stopped on a missing tree, run the git ls-tree -r -d <commit> it names in the checkout, which fetches the trees, then sync the same way. Otherwise run git fsck --connectivity-only in the checkout to see what is missing, restore it with git fetch (a shallow clone) or from a backup, then sync the same way. Every sync re-tests the hold.
path_not_utf8 (sync hold) path_not_utf8 A managed sync held one committed file because its name is not valid UTF-8 (a Latin-1 name from an older system, an archive or a network share). Git hands the name back with U+FFFD for the bytes that are not UTF-8, and no Git read or file matches that decoded name, so nothing is imported from it. Until GBRA-133 the managed sync either stopped at that file on every run or skipped it with no hold; now only the file waits and the hold names it. With sync.holds=fail the run stops with path_not_utf8 instead of holding. Rename the file to a UTF-8 name (git -c core.quotePath=true ls-files shows its exact bytes; convmv -f latin1 -t utf8 converts a Latin-1 name), commit, then gbrain sync --source <source> --no-pull. The rename clears the hold.
write_interrupted write_interrupted A transient interruption kept ending this managed write: the database ended its own statements (SQLSTATE 57014, a statement timeout or cancel) at preparation or inside its publication transaction, a statement inside that transaction ran on a plan cached before a migration changed its table (SQLSTATE 0A000, "cached plan must not change result type"; the next claim prepares it again), or its publication ran past persistence.publication_ceiling_ms and its grace and the owner cancelled it. Each interruption throws the preparation away, but it is load or latency, not the write's content, so it has its own budget: the request is claimed again after a backoff (1 s, 2 s, 4 s, 8 s, then 15 s, scheduled on the request as next_attempt_at; no claim, root lock or connection is held while it waits, and gbrain sources writer status names the waiting head transient_backoff) up to persistence.max_transient_retries times (default 5, 0 to 20), and the next interruption finishes it failed instead of preparing it again without limit. Interruptions never spend persistence.max_preparation_attempts, which preparations cut off at their deadline keep (preparation_stalled). Nothing was published: a worktree-backed write's canonical file is restored before the failure is recorded. Contention with other transactions (55P03 lock timeout, 40001 serialization failure, 40P01 deadlock) is released as database_contention uncounted, and a dropped connection or a database that is restarting or out of connections is never counted. The receipt's message and owner-only error_detail name the interruptions (attempts), the retry limit (limit, limit_key), the cause (statement_cancel, stale_plan or publication_ceiling) and the SQLSTATE (sqlstate, public). A managed sync member is held like preparation_stalled: the run moves past it and the rest of the source lands, gbrain sync status lists the hold (class page, safe action retry, runbook row), and gbrain sources retry-held re-admits it. A group's shared read the database cancels is charged once, to the first member that settles with it, never to every member; and the charge commits with the claim's release, so a crash between them never counts it twice. With persistence.preparation_deadlines off nothing is counted and no backoff applies. Run gbrain sources writer status --source <source> --json (read-only: the owner, its pool, what its writes wait on), then submit the write again with a new request_id once the database is less loaded; for a held sync file, run gbrain sources retry-held <source> and the same sync with its options. A publication_ceiling cause on a page that legitimately takes longer to publish is the user's call: ask before raising persistence.publication_ceiling_ms (or the database statement_timeout for a statement_cancel). If the same write ends this way again, report its request id with gbrain doctor --json. Do not raise persistence.max_transient_retries to get past it.
write_outcome_unknown write_outcome_unknown The database session dropped while the write was being admitted (a pooler reap, a failover, pg_terminate_backend), and it kept dropping through the re-reads, so whether the write was accepted is unknown (#6355). A single drop never reaches you: the admission attempt is re-run after 100, 300 and 900 ms, and every attempt begins by reading the retained request_id, so a re-run replays an admitted row instead of admitting again. Before this code existed the raw socket error (write CONNECTION_CLOSED …, 57P01) reached the caller while the write went on to commit, and a receipt oracle took it for a refusal. Read the request first: gbrain write-request -- <request_id> or get_write_request { request_id } (the error's 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.
connection_inherited_read_only connection_inherited_read_only The database refused the write as read-only (SQLSTATE 25006): the server connection defaults to read-only transactions (a session-level SET another client left on a pooled connection, a role or database default, or a read-only server). Nothing was written. A managed sync stops the run with it (systemic). Ask the database operator to reset the pooler's server connections, stop the client issuing session-level SET through the pooler and check ALTER ROLE / ALTER DATABASE defaults; then submit the write again.
page_body_segmented page_body_segmented (a memory verb: invalid_params with write_error: page_body_segmented) The target page stores its body in segments (a page over 1 MiB written while pages.segmented_storage was on), and this write needs the whole body as one string: remember against an entity page over 24 MiB (named, or inferred from the fact), and the other whole-body writers listed under page_body_segmented. It refused before changing anything and is not retryable. For remember, save the claim without an entity (infer_entity: false); remembering it with entity once that page accepts fact rows replaces that copy. Otherwise edit the page's file and sync it, or read it with get_page body: "auto".
page_body_rows_unreadable page_body_rows_unreadable (a memory verb: unavailable with write_error: page_body_rows_unreadable) The write had to read a page stored in segments, and the segment rows readable on the writer's connection do not cover that page's body, so nothing was saved. The message names the page. Every write that reads the page refuses the same way, so retrying does not help. The brain host's operator gives the writing role the same access to page_body_manifest and page_segment_texts it has to pages. When gbrain doctor --only segmented_tiling lists the page, its rows are missing: preview gbrain repair segmented-tiling --source <id>. See page_body_rows_unreadable.
fence_unrenderable fence_unrenderable A legacy fact row (an active facts row with no fence row number) 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: a whitespace-only claim comes back empty, ~~x~~ comes back struck, a literal <br> comes back as a line break, or another column changes. Surrounding whitespace and CRLF line endings are the one accepted difference: such a row is adopted and facts.fact takes the fence's text. A second legacy row whose normalized claim, source and visibility the page already carries is left too (duplicate_claim; a private and a world row with one text are two facts and both adopt). The cycle and the v0.32.2 migration print FACTS_FENCE_FAILED: <slug> (fence_unrenderable: N row(s), <class>); doctor fence_integrity lists the pages, fact ids and reason classes under unrenderable_legacy_facts (never the claim text). The same code refuses a planned adoption whose rendered fence does not read back as its facts; that is a gbrain planning defect, not caller input. The planner runs the publisher's own read-back check on the whole rendered fence first, so such a page is reported as unadoptable (class whole_fence) instead of being submitted. A managed adoption refused in the last day is not resubmitted: the cycle reports it as class prior_refusal with the refused request id (gbrain write-request -- <id> reads it), and a direct submitFactFenceAdoption call refuses with The same fact-fence adoption was already refused.. It is retried a day after the refusal, or at once by a build whose adoption planner revision changed. Unadopted rows hold only their own page: the phantom-redirect pass skips a phantom that owns one and redirects the others. Before v0.60.218.0 the planner could reuse a leftover fence row (one with no database owner) whose visibility differed from the legacy fact's. On a managed brain the publisher refused that page here every cycle, so no private fact was published as world. An unmanaged brain had no such check: it fenced the fact into the leftover row, and the same cycle's reconcile copied that row's visibility into the fact, so a private fact could become world. The current planner never reuses a leftover row for a fact with a different visibility unless the fact is private, and re-renders a reused row from the fact. To count what an older build left in the writer table, run the read-only scripts/diagnose/fence-adoption-census.sql on the brain host against the brain's Postgres database (its header shows the psql command). Nothing to fix in the page: the rows stay active and searchable, nothing is lost, and their pages skip destructive fact reconciliation until the rows are adopted. Report the pages and reason classes with the gbrain version. Never forget_fact a row to clear the count.
reconcile private facts permission_denied gbrain sources reconcile --apply (and its preview) found a ## Facts row that would edit, renumber or change the visibility of a stored private fact, copy a stored private claim into a row under another visibility, or copy a stored private row's context (24 characters or longer) verbatim into a world row. A row is identified by its row number and claim, so a world row that only shares a private row's claim is not a private row and publishes. The refusal names the row number, never its text. It guards against verbatim copies only; reworded text is not detected, so it is not a confidentiality proof. Sources are not compared, because rows share provenance such as "Slack import". Nothing was written. Read the stored page with the printed gbrain get --source <id> -- <slug>, keep the named row as stored in the file (or remove the copied text), then run a fresh gbrain sources reconcile <id> <slug> --preview and apply it. Change private facts with remember and forget.
maintenance_backpressure (exit 12) maintenance_backpressure A managed maintenance run (gbrain extract-conversation-facts, its cycle phase or job) publishes each page as its own request, under the same local CLI writer your own CLI writes use. Before the run it counts the requests the whole run plans; before each page's model work it checks again. It stops admitting once the writer's outstanding requests, reserved receipt bytes (persistence.limits.principal_terminal_bytes; each request reserves 16 KiB until its receipt compacts after the retention window) or permanent request ids (persistence.limits.principal_lifetime_ids; never freed) would pass 80% of their limit, so the last 20% stays free for your other writes. The message names the resource. Pages already published keep their facts and nothing is half-written. Outstanding requests: read them with gbrain sources writer status --source <id> --json; a resident gbrain serve, or the next CLI run, publishes them, then rerun the same command. Receipt bytes or request ids: run the smaller batch the message prints (gbrain extract-conversation-facts --source-id <id> --limit <n>), or wait for receipts to compact; raising the named persistence.limits.* key is the user's call.
write_quota_exhausted (exit 12) write_quota_exhausted A cumulative write cap the operator set is full (these caps are off unless set): permanent request ids (persistence.limits.principal_lifetime_ids or brain_lifetime_ids, reason: lifetime_ids) or reserved receipt bytes (principal_terminal_bytes or brain_terminal_bytes, reason: terminal_bytes). begin_page_upload refuses the same way at the staged-upload caps: staged bytes (principal_staged_bytes or brain_staged_bytes, reason: staged_bytes) or open sessions (principal_uploads, reason: open_uploads); those free when a session commits, aborts or expires, so abort_page_upload on an abandoned session also helps. detail names the limit key. Waiting does not help: ids are permanent and receipt bytes free only as receipts compact. Nothing changed. Run the fix on the brain host: gbrain config set <key> <value> (the value covers about one more year at the current rate; undo with gbrain config unset <key>), then retry with the same request_id. For receipt bytes with reclaimable slack, gbrain repair receipt-compaction second previews the retained bytes compaction would free (ids: only the raise helps). Verify with gbrain doctor --only persistence_capacity --json. Runbook.
upload_not_found upload_not_found An upload call (upload_page_part, get_page_upload, commit_page_upload, abort_page_upload) named a session this connection cannot use: no such upload_id, another connection's session, a source outside your grant or since re-created, a page deleted or re-created since begin (for mode create, a page now at the slug), or an aborted session. Every case gets the same answer, so an upload_id reveals nothing. Nothing was written. Begin a new upload with begin_page_upload and a new request_id, then send its parts from part 0.
upload_expired upload_expired The upload session passed its idle deadline (persistence.limits.upload_idle_seconds, 1 hour since its last part) or its hard deadline (upload_max_seconds, 24 hours since begin) before it was committed. Its parts were discarded and its staged bytes released; nothing was written. Run the fix: begin_page_upload again with a new request_id and send every part from part 0. An expired session never resumes.
upload_protected_content (reason: takes, facts or timeline) upload_protected_content A remote commit_page_upload replacing a page with content over 24 MiB was refused: the page holds a takes fence that remote reads hide (takes), a facts fence with a row remote reads hide (a non-world row, or a fence that does not parse: facts), or timeline rows (timeline). put_page keeps the hidden fence and rows and checks which timeline rows its content omits by comparing whole bodies; a body this size is never held whole, so the upload refuses instead of dropping them. The session was discarded and its staged bytes released; nothing was written. takes or facts: replace the page with content of at most 24 MiB through put_page (which carries the fence or the hidden rows over), or ask the user to write it on the brain host. timeline: upload again and commit with drop_timeline: true only if deleting every timeline entry is intended; otherwise send at most 24 MiB through put_page.
part_too_large part_too_large An upload_page_part call's encoded arguments are over this connection's part_max_frame_bytes (its inbound request cap, at most 4 MiB, minus a 4 KiB envelope; detail names both sizes). JSON escaping counts quotes, backslashes and control characters at their escaped size. The part was not stored. Cut the part smaller and send it again with the same part number; get_page_upload returns part_max_frame_bytes and next_part.
upload_too_many_parts upload_too_many_parts An upload_page_part call would be part number 64 plus one per 64 KiB of the declared total_bytes (one per eighth of part_max_frame_bytes when that is under 512 KiB) or later without completing the content. Each part is a stored row, so a session of tiny parts is bounded. The part was not stored. Send all remaining bytes in that part if they fit within part_max_frame_bytes; otherwise abort and begin again, cutting parts near part_max_frame_bytes (get_page_upload returns it).
part_splits_code_point part_splits_code_point An upload_page_part text starts or ends with half of a surrogate pair, which has no UTF-8 encoding on its own. The part was not stored. Move the cut before the high surrogate so the pair travels in one part, then send the part again.
write_quota_insufficient (exit 12) write_quota_insufficient A bulk run (a managed sync catch-up, a reclone, a repair) estimated from its manifest more new receipts (ids and 16 KiB reservations) than the capacity left before its producer's pause line, so it did not start. Other writes still work. Run the gbrain config set <key> <value> the message prints on the brain host, then rerun the same command. Verify with gbrain doctor --only persistence_capacity --json.
write_capacity_low (notice) write_capacity_low Not a refusal: a [gbrain notice] on write receipts, sync receipts, gbrain sync status and autopilot cycle output when a cumulative cap is at or past 80% or would run out within persistence.capacity.warn_days (30) days at its 7-day rate. Receipts carry it at most once an hour per engine and scope; sync status and doctor carry it every time. The notice says first that it is not a refusal (it never claims the call saved anything) and its fix is the read-only gbrain doctor --only persistence_capacity --json, never a cap raise. The structured capacity object in gbrain sync status names the scope, resource, days left and the config command. Nothing to redo. Read the forecast with gbrain doctor --only persistence_capacity --json and follow the runbook on the brain host; a raised persistence.receipt_retention_days comes back to the default before any cap raise.
write_capacity_backpressure (exit 12) write_capacity_backpressure A background producer (managed maintenance, conversation facts, an autopilot cycle phase, an autopilot catch-up sync) stopped admitting because a cumulative cap the operator set on its writer or the brain is past persistence.capacity.background_pause_pct (default 0.8). Interactive writes (remember, put_page, edit_page, an operator's gbrain sync, an approved gbrain repair) keep the remainder. No receipt was written. reason names the resource. Doctor persistence_capacity names the paused producers. Depends on reason. lifetime_ids: ids are never freed, so only the brain host's gbrain config set <key> <value> from the fix resumes background work; waiting does not. terminal_bytes: the same reversible raise resumes it at once, or it resumes by itself as retained receipts compact. Verify with gbrain doctor --only persistence_capacity --json.

Other error codes

These codes carry no separate reason. Each is listed so every write error code a receipt can report has a row here.

Reason Error code What it means Recovery
writer_pool_capacity writer_pool_capacity The canonical owner has no free publication slot right now; the write stays queued. Wait and poll the receipt (gbrain write-request <id>). If it persists, check gbrain sources writer status <source>.
noncanonical_value, not_kept visibility_not_applied A put_page, edit_page or capture write's frontmatter asked for visibility: private, but the page would have stayed world-readable, so nothing was written and no no-op was reported (#7841). An ingest_capture job (webhook POST /ingest, the ingestion daemon) refuses this request on every brain and dead-letters without a retry, its job result carrying the refusal (#7880); the webhook answers 202 before the job runs, so a sender reads the refusal from the job. gbrain brainstorm / gbrain lsd with --save and gbrain sources reconcile (a merge that takes a file's Visibility: private) refuse it on every brain too and store nothing (#7897). noncanonical_value: the key or value is in another case (Visibility: private, visibility: Private) or another shape (a value on the next line, a block scalar, a list, a flow mapping, an explicit or merged key), which page privacy does not read as private. not_kept: the request did not survive into the page that would be stored. The check only refuses; it never widens a page or changes what a remote caller may read or write. When the content's frontmatter is unreadable or ambiguous (the importer would hold it), a private request gets the importer's invalid_frontmatter refusal with its reason instead; nothing is written either way. Read the page and its revision (gbrain get --source <id> -- <slug>), write visibility: private on its own frontmatter line, lowercase, and submit put_page again with a new request_id. That is the supported way to make an existing page private, on a git-canonical source too (the page publishes database-only, see git_private_commit_refused).
revision_required revision_required The operation must be bound to a revision you reviewed (for example --if-version or expected_revision), and none was given: a put_page of a page that already exists without expected_revision reports this since #5385 (earlier releases said revision_conflict). Preview first, then repeat with the revision the preview printed.
revision_conflict revision_conflict The page changed after the revision this write was bound to. Nothing was overwritten. Re-read the page, merge your change, and save with the new revision.
revision_changed revision_changed An append_page with expected_revision, or a commit_page_upload whose session was bound to a revision, found the page at a newer revision. Nothing was appended or written, and the upload session is aborted with its staged bytes released. Read the page again (get_page with body: 'none'), check whether the text is still missing, then append against the new revision with a new request_id (for an upload, begin a new session).
tail_changed tail_changed An append_page with expected_tail_sha256 found a different page end: another writer appended or edited first. Nothing was appended. Read the page again (get_page with body: 'none' returns tail_sha256), check whether the text is still missing, and append against the current tail with a new request_id.
sync_cursor_replaced sync_cursor_replaced A managed sync checkpoint found that another sync run of the same source (a rediscovery, a newer sync) replaced the cursor it belongs to, so it had nothing left to publish. The receipt is a conflict; no managed-sync failure is recorded for it, and the run that awaited it goes on with the cursor that now covers the source. Nothing: let the current sync finish. gbrain sync status --source <id> --json shows that cursor. A same-run index lag keeps reporting revision_conflict.
revision_backfill_pending revision_backfill_pending The page was written before page revisions existed (an upgrade from below schema v150) and the resumable revision backfill has not reached it, so it has no revision to bind to. Its revision reads as backfill_pending, never a UUID. Nothing was written. gbrain doctor reports the backfill as revision_backfill with the pending count and any failed rows by page. A webhook capture of such a page (POST /ingest with X-Gbrain-Slug) is answered 409 revision_backfill_pending: nothing is stored and nothing is queued, so the capture exists only with its sender. An ingest_capture job already in the queue refuses the same way at write time and goes straight to dead on its first attempt (the refusal does not change on retry); its body stays in the job row until gbrain jobs prune removes it (dead jobs older than 30 days by default) (GST-2112). Resume the backfill on the brain host with gbrain apply-migrations --force-schema (it prints its progress; --yes alone does not resume it once the schema is current). Rows that used all three attempts are no longer retried: run gbrain repair orphan-children to preview orphaned child rows and torn page bodies (orphan children). After the backfill reaches the page, send a capture that got the 409 again, and re-run a dead ingest_capture job with gbrain jobs retry <job id>.
idempotency_conflict idempotency_conflict The request_id was already used for a different target, content or protocol. Use a new request_id for a different write; reuse an ID only to replay the same write.
write_pending write_pending (CLI exit 10) The write was accepted but has not committed yet. It keeps its request ID and may still commit. The CLI exits 10, not 1; a lost acknowledgment with no receipt is submission_status: "unknown" and exits 1. See CLI exit status for writes. Poll gbrain call get_write_request '{"request_id":"<id>"}', or repeat the same command with the same --request-id and a longer --wait <seconds>. Scripts that only need the write admitted pass --accept-pending (or GBRAIN_ACCEPT_PENDING=1) to exit 0, except for a receipt whose diagnostic.owner names a stale owner, which still exits 10 (stale owner).
invalid_write_wait invalid_write_wait GBRAIN_WRITE_WAIT_MS or persistence.write_wait_ms is not a whole number of milliseconds from 0 to 600000. Nothing was written. unset GBRAIN_WRITE_WAIT_MS (or set it to e.g. 30000), or gbrain config set persistence.write_wait_ms 30000.
edit_no_match, edit_ambiguous_match, edit_protected_span, edit_invalid same An edit_page edit matched nothing, matched more than once, touched a protected takes/facts section, or was malformed. detail names edit_index (and match_count). Nothing was admitted. Re-read get_page include_content:true, fix the named edit and resend with a new request ID. See partial page edits.
file_database_drift file_database_drift (also the detail of a source_changed refusal) A page's checkout file and its database copy differ, so the writer left both as they were instead of replacing one with the other (#6982). The page is held, the run reports it (details.file_holds, a FACTS_FENCE_FAILED or connector hold) and the rest of the batch continues. Nothing was overwritten. If the file holds the newer edit, gbrain sync --source <id> imports it; if the database copy is newer, re-save the page with write-through on (gbrain get <slug>, then gbrain put <slug>). When both changed, ask the user which version to keep.
storage_error storage_error The write did not commit for a reason with no more specific code. Inspect the durable request with gbrain write-request <id> on the source host and follow its message.
cancelled cancelled The request was cancelled before it committed. Nothing was written. Submit the write again if you still want it.
permission_denied permission_denied The caller is not allowed to make this write (a trust boundary, slug fence or lock). Run it as a caller that has the permission, usually the trusted local CLI on the brain host.
fence=no_source_grant permission_denied The legacy bearer token's source grant is an explicit empty list (gbrain auth rescope --token <name> --sources none), or its sources axis has drifted (an older gbrain edited its permissions JSON after the grant moved to columns; doctor legacy_token_grant_drift), so it reads and writes no source. A write accepted before that change is refused at publication. It never falls back to the default source. On the brain host: gbrain auth rescope --token <name> shows the grant and any drift. Empty grant: the refusal's fix carries the command with this token's id filled in (gbrain auth rescope-token --id <token-id> --sources <id,...>; the agent asks the user for the sources), or gbrain auth list when the token cannot be named. Drift: ask the user which grant is intended, then gbrain auth rescope --token <name> --adopt-permissions or --adopt-columns (see grant drift). Then retry with the same request ID.
scope_denied scope_denied The caller's token or grant does not cover this operation or source. Use a client with the needed scope and source grant.
not_found not_found The request, source or object named by the call does not exist. Check the id; gbrain sources list lists sources.
page_not_found page_not_found The target page does not exist in that source, or disappeared during the write. Check the slug and --source, then retry.
write_claim_lost write_claim_lost Another execution took over this request while it ran; that execution owns the outcome. Poll gbrain write-request <id>; do not resubmit under a new ID.
request_too_large request_too_large The request is larger than the configured request or recovery capacity. The message names the limit. Send a put_pages batch as smaller batches, or raise that limit on the brain host. A page under the 24 MiB page limit is never split: a transport that cannot carry it is bypassed by writing the file into the source and running gbrain sync, or by gbrain import <file> on the brain host (limits per entry point).
response_too_large response_too_large The persistence response exceeded the local transport limit. The write may still have committed. Poll gbrain write-request <id> before retrying.
writer_registration_required writer_registration_required The source needs an active canonical owner before this operation, for example activation. Claim the source on its owner host (gbrain sources writer status <source> names the next step).
writer_identity_invalid writer_identity_invalid This host's local writer identity file is unreadable or has an unknown format. Run gbrain doctor on the host; it names the identity file to repair.
writer_not_initialized writer_not_initialized The brain has no persistence identity yet, usually because migrations have not run. Run gbrain apply-migrations --yes on the brain host.
writer_coordinator_required: canonical writer must use the persistence coordinator on a tag, timeline or take write; on the client storage_error: Publication failed (P0001) writer_coordinator_required (storage_error on the stored receipt) On a managed brain whose tags, timeline_entries or takes table has a source_id column gbrain does not create, the managed writer guard of a gbrain older than v0.60.38.0 refuses every insert and update of those rows, including coordinated ones. gbrain v0.60.38.0 and later take those rows' source from their page and ignore the column; an uncoordinated delete of such a row on a live page is refused, as on every other brain. Upgrade to v0.60.38.0 or later on the brain host, then follow its recovery steps in the CHANGELOG (or repair): gbrain sync … --no-pull, gbrain extract --stale, gbrain extract timeline --source db, a previewed gbrain facts relink, then gbrain repair failed-writes (preview, then --apply --expect <hash>) for the refused put_page, add_timeline_entry and remember calls; see failed writes.
writer_coordinator_required writer_coordinator_required The operation needs managed persistence (the write coordinator) and this brain or call path does not use it. A file write refused because the path sits in a managed canonical worktree names that worktree in the message, and its detail reads root=<directory> source=<id or unknown> evidence=<marker file, managed-root registry or source binding>. Run the operation through the command the message names, on a managed brain. When the brain is not managed and the evidence is an ownership file (.gbrain-owner.json, .gbrain-owner-<hash>.json, .gbrain-managed), check it with gbrain sources writer status before removing anything: a half-finished claim is finished or rolled back through writer administration. A gbrain-managed.json an older gbrain wrote in a repository that only encloses a managed root (a dotfiles home) is named in the message; gbrain sources writer deactivate removes it (preview with --dry-run --json), then activate again.
fact_already_expired fact_already_expired The fact the write targets is already expired or withdrawn. forget_fact on an expired fact still records the withdrawal and strikes its page row before it answers this code. Nothing to do; list active facts to find the current one.
proposal_expired proposal_expired The owner's gbrain memory-proposals approve or deny came after the proposal's expires_at (proposals.ttl_hours, default 168). The proposal closes expired and nothing was written. QM reads expired on get_write_request and sends a new proposal with a new idempotency_key if the change is still wanted. The brain operator raises proposals.ttl_hours to give owners longer.
proposal_closed proposal_closed gbrain memory-proposals approve or deny named a proposal that is no longer awaiting the owner (approved, denied, expired, cancelled, failed or in conflict). It is decided once, and its decision and receipt stay as they are. Nothing was written. gbrain memory-proposals show <request_id> says how it ended; the proposer sends a new proposal if the change is still wanted.
source_writeback_required source_writeback_required The write needs a correction to the source's repository files, and this caller or profile never writes them. Make the correction in the source repository, then sync.
writer_upgrade_required writer_upgrade_required The brain's schema is older than this operation needs. A receipt whose write_error_detail.sqlstate is 42501 is the persistence protocol floor instead: see protocol guard. Run gbrain upgrade (or gbrain apply-migrations --yes) on the brain host.
skill_bundle_required skill_bundle_required The write targets a shared-skill path, which only the shared skill publisher may write. Publish the skill through the shared skill publisher instead.
core_budget_exceeded invalid_params (detail core_budget_exceeded) The write would make always-loaded core memory larger than memory.core.max_chars, or add a 51st core page. The message names the projected size, how far over it is and the largest core pages the caller can see. Nothing was written; writes that shrink core always pass. Move detail into a linked non-core page and keep a one-line pointer, or ask the user to raise the budget. gbrain core status --json shows where the characters go. See core memory budget.
core_mark_owner_only invalid_params (detail core_mark_owner_only) A remote caller tried to add or remove always_load or change core_priority. Only the owner designates core pages. Nothing was written. Resubmit without changing those keys (omitted keys keep their stored values). If the marking itself should change, ask the user to run the gbrain core add or remove command the message names. See owner only.
core_delete_owner_only invalid_params (detail core_delete_owner_only) A remote caller tried to delete a core page. Nothing was deleted. Ask the user to run gbrain core remove <slug> first; the page can then be deleted. See owner only.
core_remote_edit_refused invalid_params (detail core_remote_edit_refused) memory.core.remote_edit is refuse, so remote edits to core pages are refused. Nothing was written. Ask the user to make the edit on the brain host, or to allow remote edits with notices (gbrain config set memory.core.remote_edit notify). See remote edits.

gbrain doctor reports parked targets as the parked_effects check with the exact retry-effects command per request. When the original writer was revoked, the preview reports action: owner_revoked with authority: {ok: false, code, message} and a fix that asks the user first, and doctor names that exit instead of the retry command: the Git backup of those pages is incomplete. After the user agrees, the owner host retries a parked Git effect once under the brain owner's authority with gbrain sources writer retry-effects <source> --request-id <id> --admin-intent writer_retry_effects --expected-state <admin_state>; the effect records retried_under: owner_host. A withdrawal effect is never retried under another authority. gbrain sources writer git-durability <source> --pat-file <path> retries every parked push of the worktree after wiring the credential; a request refused on its own (revoked writer, replaced source, live claim) is listed in parked_pushes.refused with its fix, the result has status: partial, and the command exits 1. It reports persistence_capacity when lifetime request IDs or receipt bytes reach 80% of a limit, with the gbrain config set value to use; outstanding-request, queued-byte and recovery-byte limits can refuse writes without that warning.

A parked or failed Git effect no retry can ever move (#7423, #7378): the target's prefix was declared db_only after the effect was queued, so every retry parks it again; or the effect belongs to a former canonical worktree (the source was moved with set-path or a transfer), so retry-effects --request-id refuses it source_changed and --parked-pushes, which only reaches the current worktree, previews nothing (it now names those effects under former_worktree, and doctor's git_push_holds fix for them is the settle preview). Doctor parked_effects and writer status give such effects their own parked group (former_binding: the recorded worktree, the current one, the request ids and the settle preview as command), and the exact retry's refusal names both bindings with settle-effects --request-id <id> --dry-run as its fix; the bulk retry's zero never covers them (disposition). Do not claim or transfer the source to force the old effect through. Settle it on proof instead: preview with gbrain sources writer settle-effects <source> --parked-code <code> --dry-run (or --request-id <id>), show the user each effect's proof, and after they agree run the printed apply_command (--apply --expect <plan_hash>; a changed plan refuses preview_changed). An effect settles only when each target is declared db_only in the current gbrain.yml (proof db_only), or, for a former-worktree effect, a later Git effect of the current worktree committed and pushed the bytes the canonical file holds now and the already-fetched remote-tracking ref of the checkout's branch holds exactly those bytes at that path (proof superseded_remote; nothing is fetched). Each other effect is listed with its refusal: retry_instead (current binding: retry it), no_covering_receipt (write the page through gbrain first), bytes_unpushed, remote_ref_missing or remote_ref_stale (fetch in the checkout, then preview again), content_changed, content_missing, unknown_target, withdrawal_effect (never settled), recovery_open, claimed, authority_changed, source_replaced and owner_unavailable. --retire (#7985) settles an effect of a former binding that nothing current owes, on evidence instead of a remote proof: its source was replaced, or each target's page moved to a later revision, was deleted or lost its slug to another page (proof former_binding_retired; refusals page_not_moved and not_former_binding; the apply asks the user, disposition). A settlement is recorded on the effect (data.settled, every settle and unsettle appended to data.settlements); its failure, request, intent and target bytes are kept. Doctor parked_effects, writer status, the bulk retries and sync status skip settled effects. --unsettle with the same selector previews, and with --apply --expect reverses, a settlement.

Held files and content refusals

Some content refuses deterministically: the same bytes refuse on every retry. On a write (put_page, capture, gbrain import) the call fails with the code below and nothing is written. During gbrain sync the file is held instead: the rest of the source imports, the checkpoint advances, and the hold is reported by the sync result (held, held_count, holds_outstanding), gbrain sources status <source>, doctor git_held_files, get_page (file_held) and search (stale hits and the held_files notice). A held new file has no page; a page whose newer file is held keeps its last good revision and is read-only for put_page until the file is repaired, so do not retry a refused write. A hold clears by itself when the file changes, is deleted, or a newer gbrain can read it.

Every hold carries code, reason, key, line, a location-only message (never a frontmatter value), fix (the exact command) and docs (the anchor below). Walkthrough: held files.

Say to your agent: "Sync held some of my notes. Tell me what is wrong with each file and fix the ones that need no guessing."

Code (reason) What it means Recovery
invalid_frontmatter The file's YAML frontmatter cannot be read without guessing. gbrain imports frontmatter it can read exactly, quoting at most an unquoted value (author: a (b) (original: https://…) imports and is reported under recovered_frontmatter). Producer checks stay strict: gbrain frontmatter validate and the pre-commit hook still fail on it. Preview the fix: gbrain repair frontmatter --source <source>; it writes nothing until --apply --expect <hash> --yes. On a write, correct the named line and submit with a new request ID.
invalid_frontmatter (yaml_parse) YAML no rule reads safely: a mis-indented list or mapping entry, a key line with no colon. The preview lists it as needs_review with the exact line to fix by hand: one line per key, the whole value quoted. Commit and sync.
invalid_frontmatter (needs_interpretation) Reading it means choosing an interpretation: unquoted continuation lines after a value, a duplicated key, an unclosed [ or {. gbrain never imports a guess. gbrain repair frontmatter --source <source> --include-ambiguous shows the exact interpretation per file. Show the user each diff; apply only what they approve (--only <path> / --skip <path> select files).
invalid_frontmatter (ambiguous_identity_key) slug, type, id or source_id appears twice, or its line was swallowed into another value, so gbrain cannot tell which page the file is. Edit the file by hand: keep exactly one line for the key. The user decides which value is right.
invalid_frontmatter (ambiguous_protected_key) A key that decides access or provenance (visibility, derived_from, …) is malformed, duplicated, swallowed into another value, rewritten by quoting, or inside an unclosed fence. gbrain never reads such a key as a broader value. Edit the file by hand: write the key on one line with one quoted value. Ask the user which visibility is intended; never guess it.
frontmatter_slug_conflict The file's frontmatter slug: names a different page than its path does (earlier releases reported this as invalid_params). The path decides the slug. When the named slug has no page and no file (#6865), the managed sync itself removes the line after it releases its drain lease, imports the file under its path slug, clears the hold, commits the edit and keeps the declared slug as an alias; a file edited since the hold, an unfinished sync or a remote job waits for the next pass (sync.slug_conflicts.auto_remove false turns it off; slug_lines_removed counts it). The hold has three outcomes once the content-repair lane's slug-conflicts kind runs it (the maintenance run's content_repair phase, gbrain sync unblock --apply, or gbrain repair content --source <source>): removed (the named slug resolves to no page and names no other file, or to a page of a different type sharing no title token: the stray slug: line is removed, the file imported and committed, the hold cleared, with a receipt; a model under the fences.repair caps makes the same call when the two pages are not obviously different), merge recommended (merge_recommended: the two files describe the same thing; gbrain recommends the merge and names the canonical page but never merges pages by itself), or undecided (content_repair_needs_human). The lane judges the file with the screen managed sync froze it with: a hold the sync screen now admits as the file is (its slug line names the file's own page as written, or it no longer declares a conflicting slug) is imported unchanged in one guarded write that clears only the hold observation the lane read (a hold a newer sync wrote stays, with a retry), and a file sync would hold whatever the lane writes is slug_page_mismatch. Until that kind ships, the lane leaves the hold to the frontmatter repair preview below. Nothing to run when the lane removes the line: the hold clears on the sync it prints. For a recommendation or an undecided hold, gbrain sync status --source <source> --json carries the paragraph (human_reason): merge the unique sections into the canonical page by hand or decide which page keeps the slug, delete or edit the file, commit, then gbrain sync --source <source> --no-pull. human_reason asks to "decide which page keeps the slug" only when the line names a live page (a database-only page is labelled) and names any other frontmatter fixes; a hold with no verdict never asks a person, and an older gbrain's verdict is rechecked by the next sync or maintenance run. By hand at any time: remove the slug: line or make it match the path, or move the file to the path its slug names (gbrain repair frontmatter --source <source> --include-ambiguous proposes removing the line, for approval).
file_too_large Over the page size limit: 24 MiB for a Markdown page, 5 MB for a code file (limits per entry point). Every page under the limit is stored, chunked and searchable whatever its size, so this hold only fires above it, and the same bytes are held on every retry. A file sync had to read whole to refuse (over 24 MiB with segmented storage on) is not read again until it changes, gbrain is upgraded, or gbrain sources retry-held <source> schedules it; run that after changing a setting its message names. A smaller page refused by an MCP or HTTP transport limit is a different refusal: send it by file. Leave the file out of the source: read gbrain config get sync.exclude, then gbrain config set sync.exclude '<current list>,<path>'; or, if it must be in the brain, split it into files under the limit and commit. The next gbrain sync --source <source> --no-pull clears the hold, also when nothing was committed since (#6712 PR 2).
managed_image_sync_unsupported Managed sync imports image files only while multimodal embedding is on (GBRAIN_EMBEDDING_MULTIMODAL=true): the image page, its OCR text and its image vector are built by the coordinated image importer at preparation, and source_path is recorded. While multimodal embedding is off, each image import is held with this code instead of refusing the whole sync (#5493); deleting or renaming an image still reconciles its page. These holds count as missing coverage (the image is not searchable) but never escalate, because they are not a content fault. Nothing is broken. To import the images, set GBRAIN_EMBEDDING_MULTIMODAL=true on the owner and run gbrain sync --source <source> --no-pull: the next discovery re-screens every image hold and imports the files (#6529). To stop holding them instead, leave them out of the source (gbrain config get sync.exclude, then gbrain config set sync.exclude '<current list>,**/*.png'); that clears the holds on the next sync. A held image is also re-screened when it changes and on gbrain sources retry-held <source>.
content_rejected The content-sanity gate matched junk and the operator set content_sanity.junk_disposition to reject, so the file is never imported and always visible. Remove the matched junk from the file, or ask the user whether junk_disposition should go back to quarantine; that setting is the user's decision. A managed-sync hold re-screens on every sync, so either clears it on the next one.
purged_content The file (or written content) has the content hash of a page the owner purged with gbrain delete <slug> --purge, under any slug, or carries a purged claim the database refuses. Purge leaves a text-free tombstone so a stale file, re-sync or revert cannot bring the content back. Delete or edit the file and commit; an edited file imports normally. Only if the purge was a mistake, the owner lists tombstones with gbrain pages purges list and clears one with gbrain pages unpurge <slug> on the brain host; a managed-sync hold re-screens on every sync, so the next one imports it. A Google or GitHub connector item refused this way is skipped and the sync continues; gbrain sources status lists it ("skipped as purged content"). See expire versus purge.
write_gate_rejected The source is untrusted, the file reads like an instruction to an agent (an override, a standing rule, an exfiltration or credential request), and the operator set write_gate.external_mode to reject, so the file is never imported and always visible. Managed sync holds it when it freezes the file (#6712 PR 2; before, the refusal came at preparation and blocked the rest of the source); an owner allow rule (gbrain trust allow) covering the source and the file's path admits it at freeze exactly as at preparation. The hold is needs_human, and every sync re-screens it, so the setting switched or an allow rule added clears it on the next sync. Tell the user; whether to edit the file or switch write_gate.external_mode back to quarantine is their decision.
legacy_slug_conflict (explicit_id_conflict) The file has no page at its slug, and several live pages an older gbrain imported before the current slug fold (a space, an emoji, an accent or a trailing dash in the slug; no recorded file) fold to that slug (#6727). Exactly one such page is taken over by the file: the next sync imports into it (same page id, links, timeline and aliases) and records the file as its origin, instead of creating a second page. With several, sync cannot tell which page is the file's, so it holds the file and the rest of the source syncs. It holds the file the same way when the one match has a slug sync cannot write as it stands (capital letters, from a gbrain that predates lowercase slugs; the importer lowercases), rather than creating a second page beside it. With reason explicit_id_conflict (#6729), the one match carries an explicit frontmatter id that differs from the file's, so it is a different document and is not taken over. With sync.holds=fail the run stops with page_identity_changed. Twins an older sync already created are not merged by this. Ask the user which page is the file's (gbrain sync status --source <source> --json names every candidate slug). Remove each other one with gbrain delete --source <source> -- '<slug>' (soft delete, recoverable for 72 h), or rename the file if none of them is its page; with one match under a slug with capitals, which no command can address yet, keep the file held or rename it to a name that folds to another slug (it then imports as a new page beside the old one, which keeps its links). For explicit_id_conflict: give the file the page's id if it is the same document; otherwise rename the file or delete the old page. Then gbrain sync --source <source> --no-pull. The hold re-screens on every sync.
origin_conflict (no_canonical_claimant, content_differs, file_unreadable, explicit_id_conflict, visibility_differs, trust_tier_differs, twin_has_withdrawals, twin_slug_path_occupied, twin_evidence_conflicts) Several live pages of the source record this file as their origin (duplicate-origin twins, #6948). Sync used to stop the whole source with page_identity_changed; now only this file is held and the rest of the source syncs. With no reason the pages are verified duplicates: the page the path names (meta.canonical_slug), one inline body, a readable file, no conflicting frontmatter ids, one visibility and trust tier, no slug-keyed fact withdrawals or purges, no file at a twin's own slug path and no link, relationship date, timeline entry or raw payload the merge would lose. Right after that managed sync, the heal merges each other page into the canonical one (links, relationship dates, timeline, raw data, user tags, aliases and facts move; its slug becomes an alias; it is soft-deleted without touching the file, restorable for 72 h) and the next sync imports the file. A reason means a person decides: no_canonical_claimant (no page, or not exactly one, is the page the path names), content_differs (the bodies differ, or one cannot be read), file_unreadable, explicit_id_conflict (different frontmatter ids), visibility_differs, trust_tier_differs (a merge never raises or lowers a tier), twin_has_withdrawals, twin_slug_path_occupied, twin_evidence_conflicts. With sync.holds=fail the run stops with page_identity_changed. gbrain repair origin-twins --source <source> (read-only) lists every group with its pages, revisions and verdict. Verified groups: let the next sync heal them, or apply the preview now. A decision: read each page (gbrain get --source <source> -- '<slug>'), then either gbrain repair origin-twins --source <source> --slug '<kept-slug>' (the others forget the file and stay live; nothing is deleted) or soft-delete the others with gbrain delete. Then gbrain sync --source <source> --no-pull. The heal's kill switch is gbrain config set sync.origin_twins.auto_resolve false. The hold re-screens on every sync. Guide: origin twins.
page_identity_changed (several_tombstones, spelling, identity_differs) held Managed sync cannot decide which page this file is (GBRA-130). several_tombstones: several soft-deleted pages record the file as their origin (meta.identity_slugs), so reviving one would be a guess. spelling: two files differ only by letter case or separator (notes/Case.md and notes/case.md), which another platform treats as one file (meta.identity_paths); both are held. identity_differs: the file maps to a page whose own file is gone, but its frontmatter id differs from the page's (meta.identity_ids), so it is another document and must not inherit that page's facts, links and history (#6729); the page keeps its slug, id and body, and the deletion of its old file waits with the hold. A sync pass used to stop the whole source with page_identity_changed; now only these files are held and the rest of the source syncs. A dry run (and a company source's plan) still refuses the source as before, and a remote sync leaves the files for the owner's sync to hold. The hold needs a person (sync status names it page_identity_decision) and re-screens on every sync. several_tombstones: restore the page that is this file's (gbrain restore '<slug>' --source-id <source>; a live page wins over deleted ones) or purge the others. spelling: keep one spelling, rename or remove the others and commit. identity_differs: give the file the page's id if it is the same document, or rename it so its slug differs, and commit. Then gbrain sync --source <source> --no-pull.
rename_held (rename_source_changed) A renamed file's hold cleared, but the page it was renamed from changed after the rename was recorded, so the page did not move. gbrain repair frontmatter --source <source> --include-ambiguous proposes re-binding the rename to the old page's current revision; apply after the user agrees. Or restore the old file name.
rename_identity_unreadable Classic sync (GBRA-133 S-51): a file added in the same sync that removed or renamed another has a title or frontmatter id the database refused to compare (SQLSTATE 22021 or 22P05), so sync could not tell whether it is that page renamed. The new file is held and the old page keeps its id, links, facts and timeline; the rest of the source keeps syncing. A NUL byte or an unpaired surrogate in a title or id never reaches the database: sync treats such a value as absent and the pair takes the ordinary unconfirmed-rename path. Remove the characters the database cannot store from the file title and id, commit, then gbrain sync --source <source> --no-pull. The pair is decided again when the file changes or on gbrain sources retry-held <source>.
rename_reconcile_failed Classic sync (GBRA-133 S-67): a rename fell back to importing the new file, and removing the page of the old name then failed with an unexpected error (the hold records its class and code, never its message). The old page was kept and may duplicate the new one; the rest of the source keeps syncing. A transient database error and the reconcile's own "staleness unprovable" verdict still record the <rename:…> marker, which a later run converges. Ask the user before gbrain sync --source <source> --full --no-pull: the full walk removes pages whose file is gone after checking each one (it re-reads the whole source). Or remove the old page with gbrain delete --source <source> -- <slug> (recoverable for 72 h).
concurrent_write Managed sync was importing a newer Git version of the file while a database-only write (write-through off, a sandboxed or derived write) committed a different version of the same page, so the two diverge (#6194). The proof is the page's revision itself: it was written by a committed non-sync request for that page. Neither version was overwritten: the page keeps the database version, the file is held and the rest of the source syncs. Since #6340 a page that moved with no such request to name is held the same way (the hold records page_revision and expected_revision instead of a competing request), and so is a page that changed, was deleted or was re-bound in the database between the manifest freeze and the entry's turn; a page that still holds exactly what the file would import is re-bound to its new revision and passed. gbrain sources status <source> names the page and the competing request. Preview with gbrain sources reconcile <source> <slug> --preview, decide with the user which content wins, apply the resolved preview, then gbrain sources retry-held <source> and gbrain sync --source <source> --no-pull re-screen the file. A new commit of the file re-screens it too.
file_drift Managed sync would have imported a file over a database version of its page that sync never saw (#6712). Every import records its provenance (the bytes left on disk, the page revision it wrote, the parser); a page that moved since that record (a database-only write, write-through off) while its file did not change, or, in a tree walk (first sync, --full, an unreachable checkpoint), a page whose file and revision both moved or that has no usable record (an upgraded brain: none, a pre-PR 0 record, a partial one), is imported only when the import changes nothing, a sync request wrote its current revision, or its writer's write-through wrote that revision to the file. Otherwise the file is held, the page keeps the database version and the rest of the source syncs. The hold names sides (database, both, unknown) and the database request that wrote the page when there was one; a hold the live pass writes also names its Decision, side (both, unknown, deleted) and, for a deleted side, state (tombstone_edited, purged_differs, file_gone). A file_gone hold of a page with no import record says so (meta.no_import_record) instead of naming a database edit; when its file moved, gbrain repair file-drift --held lists the page moved_to and gbrain repair moved-pages folds it into the moved page. Pages under storage.keep_db prefixes whose file is clean in committed mode are not held: the pass writes the database copy back to the file (at most 200 per pass, the rest the next pass); an uncommitted edit there is held. Holds of this code never escalate; with sync.holds=fail the run stops with file_drift instead of holding. gbrain sources status <source> names the page. Compare it first with gbrain repair file-drift --source <source> --slug <slug> (no --prefer: it names the newer side and writes nothing). Preview gbrain repair file-drift --source <source> --slug <slug> --prefer database (keep the database copy, rewrite the file) or --prefer file (import the file); the preview names any file edit sync never imported that the database copy would overwrite. Decide with the user; the apply asks for their consent (exit 3) and takes --yes only after they agree (newer file changes), then gbrain sync --source <source> --no-pull. Held pages of one Decision resolve together with --held --side <side> [--state <state>]. A changed file or page revision re-screens the hold by itself.
file_wins_rewrite gbrain repair file-drift --prefer file keeps the canonical file's bytes and adds only the protected parts reconcile keeps from the database: protected frontmatter keys the file lacks (inserted before the closing ---) and database-only timeline rows (appended to the file's timeline, with a <!-- timeline --> line above a bare ## Timeline heading so they stay in it). When the resolved page also differs in anything else (a value, a tag, the title, the body), keeping the file would mean re-rendering all of it, so the preview refuses the page and nothing is written. A database-only timeline row dated before the file's own rows sorts in among them rather than after them, so it refuses too. A file-wins apply accepted before this rule existed refuses the same way when it is prepared, and writes nothing. Show the user the page's differences. Commit them into the file through the door (gbrain git commit-push) and preview again, or preview --prefer database if the database copy should win.
frontmatter_alias_limit A file whose exact bytes an older gbrain imported and validated nests YAML aliases in its frontmatter that expand past the size limit (#7018). This release refuses them on purpose, so only that file is held (its page keeps the last imported version) and the rest of the source syncs; it is never a parser regression. Reduce the alias nesting in the frontmatter (or write the values out), or remove the file, then commit and gbrain sync --source <source> --no-pull. The hold re-screens when the file changes. Before 4b such a file stopped the source as sync_parser_regression; the workaround there was GBRAIN_SYNC_PARSER_REGRESSION=hold for the process that syncs.
visibility_noncanonical The file's frontmatter asks for visibility: private in a spelling page privacy does not read: another case (Visibility: private, visibility: Private), a block scalar, a list, a flow mapping or a merge key. Page privacy reads only the exact lowercase key and value, so importing it would store a world-readable page its author believes is private. Git sync (classic and managed) holds the file and the rest of the source syncs; gbrain import (with or without a Git checkout) refuses it and imports the rest. An existing page keeps its last imported version. Company-brain connects and syncs, and the GitHub and Google connectors on a database-only source, hold it the same way (#7880); gbrain repair url-clone-fences lists a clone file whose HEAD asks for it this way under this code; apply restores the file from HEAD with its fence rows kept database-only, so the clone can pull, but does not import HEAD and reports held (#7897). put_page, edit_page, capture, ingest_capture, brainstorm --save and sources reconcile refuse the same request as visibility_not_applied. Doctor git_held_files counts the held files and the stored pages that ask for private this way (details.visibility_noncanonical). Write visibility: private on its own frontmatter line (lowercase key and value), commit, and run gbrain sync --source <source> --no-pull (or import the file again). The hold re-screens when the file changes; no frontmatter repair rewrites a privacy request. For a stored page doctor names, rewrite its frontmatter the same way with put_page or by editing its file.
tag_too_long A frontmatter tag (or an add_tag tag) is over 2688 bytes, the longest tag the btree indexes on tags store (#7052). Before this check the database insert failed with error 54000 and the write reported storage_error. On a write nothing is written; Git sync holds the file and the rest of the source syncs; gbrain import skips it and imports the rest. The message names the tag's position and size, never its text. Shorten the tag or split it into shorter tags, then write the page again (for a file: edit it, commit and gbrain sync --source <source> --no-pull).
parser_regression A file whose exact bytes imported under an earlier gbrain is now refused. It is held and the rest of the source syncs (the default; GBRAIN_SYNC_PARSER_REGRESSION=stop stops the run instead). This is a gbrain bug. Report it with the gbrain version, the file and the code; upgrade or pin the last good version. After a fixed gbrain is installed, gbrain sources retry-held <source> and then gbrain sync --source <source> --no-pull re-screen it.
settle_mismatch A live managed sync pass settled this file at the same level in three consecutive passes, but the next round never classified it settled (#6712). Instead of re-importing it every pass, sync held it at that level and stamped the rest of the source. The hold records the level and meta.mismatch_streak. The file is usually fine: a path that keeps coming back unsettled points to a broken writer, a stuck effect or a damaged record. Run gbrain doctor --json and gbrain sources writer status --source <source> --json (both read-only), fix or report what they name with the gbrain version, then gbrain sources retry-held <source> and gbrain sync --source <source> --no-pull. A mismatch that comes back is held again after three passes.
write_interrupted The database ended this file's statements (a statement timeout or cancel) at every attempt, so the sync held the file and kept going. The file is fine: no repair applies, and it is not imported until it is retried. Full reference: write_interrupted. gbrain sources writer status --source <source> --json (read-only) names the load on the write owner; reduce it, then gbrain sources retry-held <source> and the same sync with its options.
preparation_stalled The write for this file could not finish preparing within its attempt limit, so the sync held the file and kept going. The file is fine: no repair applies, and it is not imported until it is retried. Full reference: preparation_stalled. gbrain sources writer status --source <source> --json (read-only), fix what it names, then gbrain sources retry-held <source> and the same sync with its options. Runbook: catch-up stuck / held N files.
worktree_dirty The working tree holds uncommitted bytes for this file that match neither the pinned commit nor the current page (an agent mid-edit on a live checkout), and importing the pinned version would discard them (#6340). Before this release the refusal (source_changed / pinned_git_worktree_conflict) stopped the whole run; now the file is held, the local edit is untouched and the rest of the source syncs. The hold keeps the pinned blob (meta.blob_oid) and a hash of the working bytes, counts meta.attempts each time the same file is held again, and a page held three times is reported needs_human by gbrain sync status. Bytes that are committed at HEAD past the pinned target are not a conflict at all: sync imports them as HEAD has them and the later pin..HEAD diff re-imports the same bytes as a no-op. Since 0.60.179.0 (#6513) the same hold covers a pinned import whose canonical correction (a fixable fence, reflowed frontmatter) would rewrite a file that holds newer uncommitted bytes: that refusal used to block the cursor with no exit, because --retry-failed replays the same pin against the same bytes, sources refresh refuses sync_in_progress on the unfinished cursor and --acknowledge-managed refuses cursor_unfinished. Working-tree bytes that already are the correction (gbrain's own writeback, published before the request that carried it settled) are not a conflict either: the page imports and the file is left as it is. Commit the edit (or restore the file), then gbrain sync unblock --source <source> --apply re-screens every held file that is now committed and prints the sync to run (gbrain sources retry-held <source> does the same for all holds). A later commit that changes the file re-screens it on its own. Never discard or normalize the local bytes. Runbook: sync unblock.
file_unreadable Classic or managed sync held one file because it is not a readable regular file inside the source root. Sync never reads or follows it, the rest of the source imports, and the bookmark advances. Classic sync re-screens it on every run, so an out-of-band fix needs no commit. Follow the reason row below. Each hold's fix names the exact step; gbrain sources status <source> --json lists the holds.
file_unreadable (symlink_in_repo) The path is a symlink to another file in the repository. Sync reads only regular files and never follows a symlink. Replace the symlink with the regular file it stands for (or delete it), or leave it out with sync.exclude (gbrain config get sync.exclude, then gbrain config set sync.exclude '<current list>,<path>'). The next sync re-screens it.
file_unreadable (symlink_outside_root) The path is a symlink to a path outside the repository (it can point anywhere on the host), so sync never reads it. Before GBRA-133 classic sync blocked the source for three runs, then auto-skipped it. Copy the content you want into a regular file at that path (or delete the link), or leave it out with sync.exclude. The next sync re-screens it.
file_unreadable (symlink_dangling) The path is a symlink whose target does not exist. Classic sync used to drop it silently. Replace it with the regular file, or delete it and commit. The next sync re-screens it.
file_unreadable (symlink_loop) The path is a symlink that resolves back to itself. Classic sync used to drop it silently. Replace it with the regular file, or delete it and commit. The next sync re-screens it.
file_unreadable (permission_denied) gbrain cannot open the file (EACCES or EPERM), for example a file another user owns with mode 000. Before GBRA-133 classic sync blocked the source for three runs, then auto-skipped it. With sync.holds=fail it still fails the run as PERMISSION_DENIED. Make it readable to the account gbrain runs as (chmod u+r -- <checkout>/<path>, or fix its owner or a parent directory's permissions). The next sync imports it with no commit needed.
file_unreadable (not_regular_file) The path is a FIFO, socket or device in the working tree, which sync never opens. Replace it with the regular file, or leave it out with sync.exclude.
absent_from_worktree Classic sync held a file the commit names that is missing from the working tree. Before GBRA-133 it was treated as "deleted after the pin" and dropped silently. The rest of the source imports and the bookmark advances; the hold re-screens on every run and clears when the file is back on disk (it imports) or leaves the commit. Follow the reason row below. The fix is ask_user: restoring the file and committing its deletion are both valid.
absent_from_worktree (skip_worktree) A sparse checkout (or a skip-worktree bit set by hand) keeps the committed file off disk. Ask the user: widen the sparse checkout (git -C <checkout> sparse-checkout add <dir>; for a hand-set bit, git -C <checkout> update-index --no-skip-worktree -- <path> and git -C <checkout> restore -- <path>) and the next sync imports it; or leave it out with sync.exclude. Keeping it held is also safe.
absent_from_worktree (deleted_locally) The committed file was deleted from the checkout and the deletion is not committed. Ask the user: restore it (git -C <checkout> restore -- <path>) and the next sync imports it; or commit the deletion (gbrain git commit-push --path <checkout> -m 'Delete <path>' -- <path>) and the next sync clears the hold.
unsupported_path (not_utf8, control_character) Classic sync: the file's name is not valid UTF-8 (not_utf8, a Latin-1 name from an old archive) or contains a control character (control_character: a tab, a newline or another byte below 0x20). Git stores a name as bytes and a page path is text, so the file cannot be imported under its own name. Sync reads the diff as bytes (git diff --raw -z), never as a lossy decoding: before this the file was checkpointed as "deleted after the pin" with no message (not_utf8) or skipped as a malformed name naming no path (control_character). The hold key is /gbrain-bytes/ plus the path with every byte outside a printable UTF-8 character, and every %, written %XX (notes/caf%E9.md); it decodes to the exact bytes and never equals a Git path. The message shows the name C-escaped (notes/caf\351.md) with an item id (the first 16 hex digits of the bytes' sha256). The rest of the source syncs and the checkpoint advances. Rename the file to a valid UTF-8 name without control characters and commit. The fix's user_message gives a rename command that spells the old name with printf escapes (printf 'notes/caf\351.md\000' | xargs -0 -I{} git mv -- {} 'notes/caf_.md', run from the source's checkout), so no raw bytes go on a command line; then gbrain sync --source <source> --no-pull imports the file and clears the hold. The hold re-screens on every sync: it stays while a file has that name and clears once the name leaves the tree (renamed, deleted or excluded).
gitlink_not_followed (notice, not a hold) Classic sync: the range added a gitlink (a submodule or an embedded repository, mode 160000). It records another repository's commit, not files, so its contents are not indexed. Reported once, in the run that passes it: the result's gitlinks_not_followed lists the paths and one stderr line names them. Nothing is held and the checkpoint advances. Nothing to fix. To index the linked repository, check it out and add the checkout as its own source (gbrain sources add <name> --path <checkout>).
sync_parser_regression Sync stopped without advancing because it would hold a file whose exact bytes imported before, and GBRAIN_SYNC_PARSER_REGRESSION=stop (opt-in; the default holds the file) is set for the process that syncs. This is a gbrain bug, not a content problem. Report it with the gbrain version, the file and the code; upgrade or pin the last good version, then gbrain sync --source <source> --no-pull. To keep syncing meanwhile, unset GBRAIN_SYNC_PARSER_REGRESSION for the process that syncs (ask the user).
takes holder (invalid_params) takes_add, or takes_supersede with an explicit holder, was given a holder the takes fence cannot carry: empty, whitespace, or not world, brain, people/<slug> or companies/<slug> (a legacy bare slug is accepted). The value is trimmed first, so " world " is stored as world. Nothing was written: before this release such a holder was published into the fence and every later takes write on that page was refused target_fence_malformed. A supersede without an override keeps the row's stored holder. A page whose stored holder is already malformed still refuses every takes write (invalid_fence); gbrain repair fences is the way out. Resend with a holder in that grammar (holder: me on the brain host resolves the owner's holder). For a page already carrying a malformed holder, preview gbrain repair fences --slug <slug> and apply it, or edit the who cell by hand. Format: holders.
changed_since_preview A hash-bound repair apply (gbrain repair frontmatter --apply --expect <hash>, gbrain repair fences --apply --expect <hash>, gbrain repair content --apply --expect <h1>[,<h2>]) found a file, its proposed change or its page different from what the preview showed, so that item was not written; the rest of the approved set still applied. Preview again with the same selection and apply the new hash (for the content lane, one hash per kind in lane order). For frontmatter, show the user the new diff first; a fence repair needs no extra consent (fence reason).

Fence holds (invalid_fence)

A page's facts and takes fences are its structured rows (format). A coordinated write (managed sync, managed gbrain import, put_page on a managed brain, managed file repair) refuses a fence it cannot import without dropping or guessing rows: code invalid_fence, wire error invalid_params (take_row_collision for a stored-row collision). During managed sync the file is held instead and the rest of the source syncs. The message reads Fence <reason>: in the <facts|takes> fence (<body|timeline>), row(s) N, column(s) C, at line L. (the parts that apply; the line counts within the section), then the fix. It names fence, section, row numbers, column names and lines only, never a claim, holder or cell. A failed receipt keeps the location in write_error_detail.fence (row numbers stay on the brain host).

A managed maintenance write (fact-fence adoption and the cycle's other page writes) is checked the same way before it is submitted, over the page's whole body and timeline: a page that already carries a defect no adoption clears (for example a second facts fence in its timeline) is skipped with the fence reason in failed_pages, no request is created, and the other pages still go. The fence census counts the stored defect (gbrain doctor --only fence_integrity --json), and gbrain repair fences --source <source> previews it where a repair applies.

What a fence hold carries. Every surface that shows a hold (gbrain sources status <source>, doctor git_held_files, get_page.file_held, the sync result) gives the same location-only fields:

  • fence: reason, fence (facts or takes), section (body or timeline), rows (row numbers), columns (column names) and line (the first bad line, counted within the section).
  • The reason's tier, the repair that clears it (deterministic, resolver, llm or manual), and auto_retry, whether the maintenance run clears or retries it with no one acting. The table below lists both for every reason.
  • After a repair has tried the file, fence_repair: that attempt's reason, tier and at, next_attempt_after (when the maintenance run tries it again; null when it will not), and gate and rows when a proposed repair was rejected.
  • fix, the next command (a single held file's preview, gbrain repair fences --source <source> --only <path>), and docs, the reason's anchor below.

What gbrain fixes by itself. Before refusing or holding, every write path runs the fence through a lossless normalizer: a missing end marker with only blank lines after the table, two-dash takes markers above a table, zero, negative or duplicate row numbers (new numbers come after every number the page and its stored rows ever used), header aliases and column order, header-level defaults (confidence 1.0, notability medium, visibility private), enum synonyms (critical → high; public → world only on a world-visible page, else private), invented facts kinds (mapped to the closest kind, the original word kept in context), a short list of takes kind synonyms, assistant holders (System, assistant → brain) and percent confidences (every rule). It never changes a claim, an existing row number or a valid cell, and never makes a row more visible. A fence it fixes completely is written in its normalized form: managed sync commits the rewritten file (a read-only mirror keeps it database-only; a company-brain source refuses source_writeback_required naming the fence), and the result reports fences_normalized (count, by_class, writers, sample paths for local callers). A write also carries one fence_normalized coaching notice: the stored page differs from what was sent, so re-read it with get_page before editing; remember and takes_add write rows that never need it. gbrain sync --dry-run lists would_normalize beside would_hold. gbrain config set fences.normalize false turns normalization off: a fixable fence is then held or refused like any other.

What the normalizer cannot fix exactly is refused or held as below; a refusal lists every blocking problem in fence_issues ([{ fence, section, row, column, line, class, allowed }], where allowed is the column's vocabulary), so the caller can correct all of them at once.

Legacy (unmanaged) sync, gbrain import on an unmanaged brain and other direct imports store a fence the normalizer cannot fix as written (bad rows skipped) and never hold it; the result reports it in fence_issues. Two documented exceptions keep blocking with the typed refusal instead of holding: sync.holds=fail, and company-brain sources, which never hold and never rewrite repository files (fix the fence in the repository and commit).

Repair. Fence holds clear by themselves: the maintenance run's fence_repair phase repairs held files and stored pages whose fences do not parse, on the brain's owner host. A repaired file is committed like any page write on a managed source; on a legacy source it is backed up under ~/.gbrain/backups/ and left for you to commit. To see what it would change, or to do it now:

gbrain repair fences --source <source>                          # preview: read-only, no model call
gbrain repair fences --source <source> --apply --expect <hash>  # the apply command the preview prints

The preview lists each held file and stored page with its reasons, rows and columns, the tier that fixes it and the estimated model cost against the remaining daily cap, and prints the apply command with its --expect hash. Applying needs no extra consent. Tier 1 and 2 changes are exact rules; Tier 3 sends only the fence header and the rows it must realign (never valid rows, never the rest of the page) to the repair model (models.fence_repair, or unset the first measured model with a key: openai:gpt-6.1-sol, else anthropic:claude-opus-5-5), within fences.repair.max_usd_per_page ($0.30) and fences.repair.max_usd_per_day ($1.00) (spend). Every tier's output passes gates (a) to (g) before anything is written. --no-llm keeps a run to the free tiers and --max-usd <n> lowers its cap; raising spend (gbrain config set fences.repair.max_usd_per_day <usd>) or turning model repair back on (gbrain config set fences.repair.llm true) is the user's call. MCP and thin-client callers cannot run a repair: the hold's fix names the owner-host command to hand to the user. Walkthrough with real output: fence repair.

A manual reason needs a person, because gbrain never guesses it: read the page (gbrain get --source <source> -- <slug>), edit only the named fence in the file (never the frontmatter), commit, then gbrain sync --source <source> --no-pull. gbrain sources status <source> lists every fence hold with its location. To add rows without hand-editing a table, use remember (facts) or takes_add (takes).

Say to your agent: "Sync held a page because of its facts table. Show me which rows are wrong and fix them."

How many are left. gbrain doctor --only fence_integrity counts, per source, every malformed fence still waiting, once each: a held file, a stored page whose fence does not parse (for example one an older release imported as written), and a checkout file not yet synced. Each is split by the tier that would clear it: deterministic (the normalizer fixes it the next time the file syncs or the page is written), resolver (a holder name to resolve), llm (a table only a rewrite can realign) and manual (an edit only a person can decide). It also shows the oldest hold's age, the fences normalized in the last 7 days with their top writers (a source at 20 or more warns: something keeps writing malformed fences) and the model-repair caps fences.repair.max_usd_per_page (default $0.30) and fences.repair.max_usd_per_day (default $1.00) with today's spend. Each run scans for at most GBRAIN_DOCTOR_FENCE_TIMEOUT_MS (10 s) and resumes where the last one stopped; until a scan finishes the check is partial and never ok. The maintenance run repairs the deterministic and resolver ones by itself, and the llm ones while model repair is on and within the caps; gbrain repair fences --source <source> previews the plan.

Say to your agent: "How many broken facts or takes tables are left in my brain?"

Each reason's Tier is the repair that clears it (- when that depends on the page, which is screened again); Auto says whether the maintenance run clears or retries it with no one acting.

invalid_fence reason What it means Tier Auto Recovery
header_unmapped The header has a column with no canonical name and no known spelling, so its cells cannot be placed. llm yes Repaired by the next maintenance run (preview: gbrain repair fences --source <source>). By hand: rename each column to its canonical name. Format: header spellings.
no_header The fence has table rows but no header row naming claim and kind. llm yes Repaired by the next maintenance run. By hand: add the canonical header as the first table line. Format: markers.
row_before_header Rows sit above the header row. llm yes Repaired by the next maintenance run. By hand: move them below the header. Format: markers.
short_row A row is missing a cell in the middle, so its columns are ambiguous. A row short only in its optional trailing cells parses. llm yes Repaired by the next maintenance run. By hand: add the missing cells so every column lines up. Format: facts, takes.
extra_cells A row has more cells than the header, and removing empty cells does not line it up (stray empty cells with one valid removal are rewritten by themselves). Often an unescaped | cut a cell, usually the claim, in two; no gate can tell that from a misplaced cell, so it is never sent to the model. In a fence with no header, a row that starts with a row number is read by position the same way. manual no Join the cut cell with |, or remove the extra cell. Format: facts, takes.
claim_split A facts kind cell holds text, not a kind word (more than three words, sentence punctuation, a link or strikethrough): usually the end of a claim an unescaped | cut in two, with the kind cell missing. gbrain does not store it as a kind note. In a fence with no header, a row that starts with a row number is read by position, so its third cell is the kind. manual no Join the text back into the claim with | and write the kind. Format: facts.
holder_unresolved A takes who cell is not world, brain, people/<slug> or companies/<slug> (for example a person's display name). resolver yes Rewritten by the next maintenance run when it resolves to exactly one verified people/ or companies/ page (never a private page on a world-visible page). Otherwise write one of those forms by hand. Format: holders.
missing_begin An end marker has no begin marker before it. manual no Add the begin marker above the table, or delete the stray end marker. Format: markers.
split_rows A fence has no end marker and its rows are split by blank lines or text, so gbrain cannot tell which rows belong to it. manual no Join the rows into one table and add the end marker after the last row. Format: markers.
unclosed_trailing_content A fence has no end marker and lines holding a pipe follow its table, so the rules cannot tell table rows from prose. llm yes The maintenance run asks the repair model whether the tail is prose; a prose tail closes the fence after its last row (on a private page by itself; on a world-visible page after the user approves the lines it shows, see tail_exposure_approval). A tail of plain prose with no pipe never reaches the model: it closes by itself on a private page and waits for approval on a world page. By hand: add the end marker directly after the last table row. Format: markers.
unclosed_ambiguous_tail A fence has no end marker and the lines after its table are not plain prose: a row written without pipes, a mention of a fence marker, or a tail the repair model read as rows or could not classify. manual no Add the end marker directly after the last table row and fix the rows below it, or wrap a marker mention in backticks; gbrain does not guess where the fence ends. Format: markers.
tail_exposure_approval A fence on a world-visible page has no end marker and prose follows its table; gbrain can close it after the last row, but the lines after the table would then be visible to readers of the page, so the close waits for the user. deterministic no gbrain repair fences --source <source> --only <path> previews the close and prints the lines that would become visible with the apply command (--apply --expect <hash>); run it once the user agrees. Unattended runs never close it. Format: markers.
quoted_marker A line quotes a facts or takes fence marker in prose (text follows the marker on its line, or the line is a blockquote), so the section reads as having a repeated or unclosed fence. deterministic yes gbrain repair fences --source <source> --only <path> previews wrapping each mention in backticks and prints the apply command; gbrain sync unblock --source <source> --apply and the maintenance run apply it, with a receipt per file. Or wrap the mention in backticks yourself. Format: markers.
marker_near_miss A line uses the two-dash takes marker (<!-- gbrain:takes:begin -->) or mentions it with no takes table after it. Two-dash markers directly above a takes table are rewritten by themselves. manual no Use the exact three-dash markers around the takes table, or wrap a mere mention in backticks. Format: markers.
repeated_marker A body or timeline section has a second begin or end marker for the same fence outside code. Two or more fences that each have both markers, the same canonical header and nothing but table lines inside are merged by themselves (merge_fences: later rows appended, exact duplicates dropped, colliding numbers renumbered, a repeated section heading removed). manual no Give the extra fence both markers and the first fence's header and move any other text out of it, so the next write or maintenance run merges them; or merge by hand, keeping one begin and one end marker per fence in that section with every row in one table. Format: markers, what gbrain rewrites.
takes_in_facts A facts fence holds a takes table. manual no Move the rows into a takes fence (or add them with takes_add), or rewrite them as facts rows. Format: takes.
superseded_ambiguous Two rows share a number and a superseded by #N reference names that number, so renumbering could repoint the reference. manual no Decide which row keeps the number, give the other a number above every number on the page, and fix the reference. Format: row numbers.
enum_unmapped A facts kind, visibility or notability cell holds a value outside the allowed list and its synonyms (the message names the column and the allowed values). manual no Use one of the allowed values. Format: facts.
weight_missing A takes row has no weight, or the header has no weight column. Takes have no default weight. manual no Add a weight from 0 to 1. Format: takes.
holder_missing A takes row has no holder, or the header has no who column. manual no Add the holder: world, brain, people/<slug> or companies/<slug>. Format: holders.
confidence_out_of_range A facts confidence or takes weight is not a number from 0 to 1 (a percent such as 85% is rewritten by itself). manual no Write the intended value as a decimal such as 0.8. Format: facts, takes.
claim_value_invalid A facts claim_value is not a number. manual no Write a number (1,234 separators and a k/M/B suffix are allowed) or leave it empty. Format: facts.
takes_kind_unsupported A takes kind is not fact, take, bet or hunch and is not one of the few synonyms gbrain maps (a kind the schema pack declares but the parser does not accept included). gbrain never chooses a takes kind for you. manual no Use one of the four kinds. Format: takes.
unparseable The fence does not parse cleanly: most often it has no end marker, or a row number is not a positive whole number (column #). - yes Usually repaired by itself on the next write or maintenance run. By hand: add the end marker directly after the last table row, or fix the named row number. Format: markers.
row_collision Two rows of the same fence kind share a row number, in one fence or across the body and timeline (rows lists the numbers). - yes Usually renumbered by itself. By hand: give one row a new number above every number used on the page. Format: row numbers.
quoted_fence_rows A fence sits inside a code block or inline code span, so readers treat it as an example and importing would remove the stored rows it holds. - no Move the fence out of the code, or delete the fence to remove its rows. Format: markers.
stored_row_collision A new takes row's number already names a different stored take that is not in the page's fence (wire take_row_collision). - no Renumber the new row, or add the stored take back to the fence. Format: row numbers.
withdrawn_claim_in_malformed_fence A facts fence that does not parse holds a claim the user withdrew, so gbrain cannot tell whether the row should stay withdrawn. - yes Repair the fence so it parses (gbrain repair fences --source <source> previews it); the withdrawn row then stays withdrawn. Format: examples.
target_fence_malformed A verb that appends to or edits a page (remember, extract_facts, takes_*, facts relink, edit_page) found that page's stored fence does not parse and cannot be normalized in the same write (edit_page and the other takes writes never normalize). A fact write that would re-render a facts fence the parser reads with warnings (a malformed row, or a header naming a column outside the facts schema) refuses the same way, so the skipped rows are never dropped. Memory verbs keep their v1 code (invalid_params, detail: invalid_fence). - yes The maintenance run repairs the stored fence; to do it now, gbrain repair fences --slug <slug> on the brain host. Or read the page, fix the named fence (or write the whole page with put_page, which normalizes what it can and names every row it cannot), then retry with a new request_id. Format: examples.
prepare_time Hold only: the file passed the content screen, but its fence was refused while it was prepared against the stored page (a stored-row collision, a withdrawn claim, rows quoted in code). fence.reason names which. Managed sync holds it in the same run instead of blocking. - yes Fix it as its fence.reason says. After a database-side fix (for example removing the conflicting take), gbrain sources retry-held <source> re-checks the file. Format: what gbrain never guesses.
normalizer_failed The normalizer or its validator failed on this fence (a gbrain bug); the fence was not rewritten. A coordinated write refuses; a legacy import stores the page as written. manual no Run gbrain doctor --json and report it with the gbrain version; an upgrade re-screens the file. Format: what gbrain fixes.
llm_unavailable The repair model timed out, was rate-limited or returned a server error. llm yes Nothing to do: the next maintenance run (or gbrain repair fences --apply) retries. Format: tiers.
llm_empty The repair model returned nothing for the fence. llm no Fix the named rows by hand. The same file is not sent to the model again until it, the model (models.fence_repair) or gbrain's repair rules change. Format: tiers.
llm_refused The repair model declined to repair the fence. llm no Fix the named rows by hand; the same file is not sent to the model again until it or the model changes. Format: tiers.
llm_malformed The repair model did not return exactly one table, or wrote text outside it. llm no Fix the named rows by hand; the same file is not sent to the model again until it or the model changes. Format: tiers.
llm_truncated The repair model stopped before finishing; its output is rejected even when it parses. llm no Fix the named rows by hand; the same file is not sent to the model again until it or the model changes. Format: tiers.
llm_declined The repair model answered HOLD: a row has more than one reasonable reading (two values for one column, or a cell that fits two columns), so it declined to guess. llm no Fix the named rows by hand; the same file is not sent to the model again until it, the model or the rules change. Format: tiers.
llm_disabled Model repair is off (fences.repair.llm false), so a fence only Tier 3 can realign waits. llm no Fix the named rows by hand, or ask the user before turning model repair back on: gbrain config set fences.repair.llm true (it spends within the caps). Format: tiers.
no_measured_model models.fence_repair is unset and no model the fence-repair eval measured as accurate enough (openai:gpt-6.1-sol, anthropic:claude-opus-5-5, anthropic:claude-fable-5-1) has a provider key on this brain, so model repair is off by default. llm no Fix the named rows by hand, or ask the user which model to trust, then gbrain config set models.fence_repair <provider:model> (an explicit model always runs). Format: tiers.
budget_exhausted The page's repair estimate is over fences.repair.max_usd_per_page or over what is left of fences.repair.max_usd_per_day today (UTC). A repair run stops with exit 1 naming the spend, the cap, the reset time (next 00:00 UTC) and the pages waiting. llm yes Nothing to do: repairs resume after 00:00 UTC. Raising a cap is the user's call: gbrain config set fences.repair.max_usd_per_day <usd> (or fences.repair.max_usd_per_page). Format: tiers.
no_pricing A spend cap the user set is in force and gbrain has no price for the repair model, so no call was made. Under the default caps an unpriced model runs, metered at an estimated ceiling. llm no Look up the model's per-token price and register it on the brain host: gbrain pricing set <model> --input <usd> --output <usd> (registering a model price). The next run repairs it. Format: tiers.
ledger_unavailable The spend ledger could not be read or written, so no model call was made. llm yes Nothing to do: the next run retries. If it keeps happening, check the database with gbrain doctor --json. Format: tiers.
owner_unavailable This host is not the brain's owner host, and fence repairs run only there. - yes Run gbrain repair fences on the owner host (gbrain sources writer status <source> names it). A remote caller hands that command to the user. Format: tiers.
owner_cli_required The maintenance worker may not apply this managed-file repair; it must be applied from the owner host's CLI. - no On the owner host: gbrain repair fences --source <source>, then the printed apply command. Format: tiers.
host_mismatch Another host id owns this source's checkout; the hold names both ids (first 8 characters). Two environments on one machine with different GBRAIN_HOME identity files (a launchd or cron worker and a shell) look exactly like this. Retrying from this host cannot change the answer. - no Run gbrain repair fences --source <source> on the owner host (gbrain sources writer status --source <source> --json names it), or give the worker and the shell one GBRAIN_HOME. Never copy or regenerate host.json: a new identity orphans the ownership recorded for the old one. Format: tiers.
transfer_in_progress A writer transfer of the source is prepared and its worktree is draining, so no host may write it yet. - yes Nothing to do: the next run repairs it once the transfer is accepted or cancelled; gbrain sources writer status --source <source> --json shows the state. Format: tiers.
clone_in_progress A topology clone or reclone of the source's checkout is in progress and its worktree is recovering. - yes Nothing to do: the next run repairs it once the clone finishes; gbrain sources writer status --source <source> --json shows the state. Format: tiers.
incarnation_changed The source's checkout binding belongs to an earlier incarnation of the source (it was removed and re-added, or restored), so the checkout it names is not this source's. - no On the brain host, review gbrain sources writer status --source <source> --json and re-bind the checkout; the next run after that repairs the file. Format: tiers.
local_path_missing This host owns the source's worktree but has no checkout path registered for it. - no On the brain host, review gbrain sources writer status --source <source> --json and register the checkout again; the next run after that repairs the file. Format: tiers.
coordination_path_missing This host's registration for the source has a checkout path but no coordination directory (where the physical-root stamp and locks live). - no On the brain host, review gbrain sources writer status --source <source> --json and repair the registration; the next run after that repairs the file. Format: tiers.
sync_in_progress A write in flight names the file, or the file is still ahead in a running sync's frozen manifest (the sync would refuse it on its raw hash if a repair changed it first), so this one candidate waits; the rest of the source is repaired while the sync runs. A held file is not busy. When the busy set itself cannot be read, every candidate waits. - yes Nothing to do: the next run retries. To finish the sync now: gbrain sync --source <source> --no-pull. Format: tiers.
time_budget The repair run reached its time budget (the maintenance phase stops at the smaller of 300 s and a third of the job's remaining deadline). - yes Nothing to do: the next run resumes where it stopped. Format: tiers.
changed_since_read The file changed after the repair read it, so nothing was written. - yes Nothing to do: the next run reads it again. Format: tiers.
changed_since_preview gbrain repair fences --apply --expect <hash> found the file's bytes or the page's revision changed since the preview, so that item was not applied. - no Preview again with the same selection and apply the new --expect hash. Format: tiers.
still_invalid Gate (a): the proposed repair still does not parse cleanly. Nothing was written. - no Fix the named rows by hand. Format: gates.
claim_changed Gate (b): the proposed repair changed claim text. Nothing was written. - no Fix the named rows by hand. Format: gates.
row_number_changed Gate (c): the proposed repair changed or dropped an existing valid row number. Nothing was written. - no Fix the named rows by hand. Format: gates.
visibility_loosened Gate (d): the proposed repair made a row more visible. Nothing was written. - no Fix the named rows by hand; ask the user which visibility is intended, never widen it yourself. Format: gates.
row_count_changed Gate (e): the proposed repair added or dropped a row, or left one outside the fence. Nothing was written. - no Fix the named rows by hand. Format: gates.
cell_changed Gate (f): the proposed repair changed a cell no named rule allows (a valid weight, holder, date, source, confidence or context). Nothing was written. - no Fix the named columns of the named rows by hand. Format: gates.
protection_loosened Gate (g): the proposed repair would show text the privacy boundary hid before it. Nothing was written. - no Add the end marker where the fence really ends. Format: gates.

A managed source a fence refusal blocked before this release recovers on its next sync with no command: the file is held and the rest imports (gbrain sync --source <source> --no-pull does it now).

A source that a gbrain older than v0.60.47.0 blocked on one of these refusals recovers on its next sync (scheduled or manual) with no ledger surgery: the blocked request is converted in place and reported as converted_from_failed. To do it now run gbrain sync --source <source> --no-pull. gbrain config set sync.holds fail makes sync fail closed for teams that want it. Escalation: more than GBRAIN_SYNC_HOLD_ESCALATE_COUNT (default 50) holds in a source, or more than GBRAIN_SYNC_HOLD_ESCALATE_PCT (default 5%) of a run's screened imports (at least 40), sets holds_escalated and makes doctor git_held_files fail: a generator or an upgrade is likely writing or reading files wrong.

The content-repair lane

Fence and slug-conflict holds clear by themselves: the maintenance run's fence_repair phase runs the fences kind and its content_repair phase runs every other kind of the lane (src/core/repair/content-lane.ts), and gbrain sync unblock --source <source> --apply runs the lane on the held paths now. Each repair is a hash-bound write with a receipt and a Git trailer; a model decides only the cases the deterministic rules mark ambiguous, under the fences.repair caps, and every byte written comes from a rule and passes the gates. The lane records five outcomes a person reads, each with the agent operator envelope (code, message, why, fix.next); gbrain errors <code> explains each offline. Walkthrough: held files.

Say to your agent: "Sync is holding a few files. Repair the ones gbrain can and tell me what it wants me to decide about the rest."

Code What it means Envelope
unclosed_ambiguous_tail An invalid_fence reason: a fence has no end marker, text follows its table, and the repair model read the tail as table rows written without pipes (rows) or could not tell (unsure), so gbrain will not choose where the fence ends. Nothing was written; the memo keeps the same bytes from costing twice. fix.next: tell_user_to_run, actor user: the hold's fix is the read-only preview naming the fence, section and last row; the person adds the end marker after the last real row (moving any rows the tail holds into the table), commits, then gbrain sync --source <source> --no-pull. why: closing after the wrong row would hide rows or expose text.
tail_exposure_approval An invalid_fence reason on a world-visible page: the repair model read the trailing lines as prose, so closing the fence after its last row is safe for the table but makes those lines visible to remote readers. The close is previewable, never unattended: the preview prints the exact lines (L1-L2) that would become visible and the hash binds them. paid: false. fix.next: ask_user, actor user, consent: []: the hold's fix is gbrain repair content --source <source> --only <path> --apply --expect <hash> with preview_argv the lane preview and plan_hash the hash; relay the preview's exposed lines, run the fix only after the user agrees. A changed tail invalidates the hash (changed_since_preview). why: the privacy boundary hid those lines until now.
merge_recommended A frontmatter_slug_conflict hold whose two files describe the same thing (a duplicate person or company page): the lane's deterministic tier found something to merge into and the model answered merge_into <canonical>, so removing the slug: line would have minted a second page. Nothing was written; the hold carries meta.content_repair: { action: 'merge_into', canonical } (codes and slugs only) and sync status renders the paragraph. gbrain does not merge pages by itself yet. fix.next: tell_user_to_run, actor user: "This file and page <canonical> describe the same <type>; gbrain recommends merging the unique sections of <path> into <canonical> and deleting <path>, then committing; the hold clears on the next sync." fix.argv reads both pages (gbrain get --source <source> -- <slug>); verify is gbrain sync status --source <source> --json. Not retried until the file changes.
content_repair_needs_human A frontmatter_slug_conflict hold the lane could not decide: the deterministic tier marked it ambiguous and the model answered needs_human (or model repair is off, out of budget or unavailable for the day). Nothing was written; the hold carries meta.content_repair: { action: 'needs_human' } and sync status says needs_human: true. fix.next: tell_user_to_run, actor user: "gbrain could not decide whether <path> and <canonical> are the same page; decide which keeps the slug: remove the slug: line, move the file, or merge the pages, then commit." A budget or model wait names its setting instead (fences.repair.max_usd_per_day, fences.repair.llm, consent paid, fix.next: ask_user). verify is gbrain sync status --source <source> --json.
slug_page_mismatch A frontmatter_slug_conflict hold the lane judged with the same screen managed sync froze it with, and sync would still hold whatever the lane writes: sync files the file as page <slug> (the page that records it as its origin, or its path-derived slug), but the path derives another slug, or the slug: line reaches that page only through an alias or another spelling. Removing the line would not clear the hold, so nothing was written; the hold carries meta.content_repair: { action: 'remove_slug', reason: 'slug_page_mismatch', named } with the other slug. Earlier releases reported this as a generic still_invalid ("the frontmatter needs other changes too") or skipped it as already_exempt. fix.next: run, actor agent: make the slug: line name <slug> exactly, or move the file to the path that derives <slug>, commit, then gbrain sync --source <source> --no-pull. fix.argv is gbrain repair content --source <source> --only <path> (read-only preview); verify is gbrain sources status <source> --json.

Worktree refresh refusals

gbrain sources refresh <source> is the one supported way to move a managed checkout to new upstream commits. It runs on the source's registered owner host, fetches, then refuses new writes to every source that shares the checkout while queued writes finish, fast-forwards with git merge --ff-only and syncs each of those sources with --no-pull. Each refusal below prints code, a one-line cause, a literal fix with the real source filled in and this anchor (--json puts them in one object on stdout); the command exits 1.

Say to your agent: "Pull the latest commits into my notes source." or "The refresh was refused. What do I need to do?"

Reason Error code What it means Recovery
refresh_not_managed refresh_not_managed The brain is not managed, or the source has no claimed checkout. Plain sync already pulls such a source, so there is nothing to coordinate. gbrain sync --source <source>.
refresh_not_owner refresh_not_owner This host is not the source's registered owner, and only the owner may move its checkout. Run gbrain sources refresh <source> on the owner host; gbrain sources writer status <source> names it.
refresh_no_upstream refresh_no_upstream The checkout's branch tracks no upstream, HEAD is detached, or the checkout is not a Git checkout at all (gbrain never initializes Git on its own), so there is nothing to fast-forward to. git -C <checkout> branch --set-upstream-to <remote>/<branch> (the fix fills in the real values), then retry. A checkout that is not Git has nothing to refresh; making it a clone with an upstream is the user's call.
fetch_failed fetch_failed git fetch failed or did not finish within sources.refresh_fetch_timeout_ms (default 120000; GBRAIN_REFRESH_FETCH_TIMEOUT_MS; --fetch-timeout-ms wins over both). Nothing changed and no refresh record was written. Retry. For a slow remote, raise the bound with --fetch-timeout-ms <ms> or gbrain config set sources.refresh_fetch_timeout_ms <ms>. Credentials are the user's: ask them to fix authentication rather than changing the remote.
git_unavailable git_unavailable A git command that reads the checkout's branch or remote (symbolic-ref, remote, config --get branch.<branch>.remote or .merge) failed or did not finish, so the checkout's state is unknown. The message names the command and git's first error line. A detached HEAD or an unset key is not this refusal. Nothing changed and no refresh record was written. Run git -C <checkout> status to see why git cannot read the checkout, repair what it reports, then retry gbrain sources refresh <source>.
refresh_diverged refresh_diverged The checkout has commits its upstream lacks, so a fast-forward is impossible. Nothing changed. Ask the user, then publish the local commits merged with the upstream: gbrain git commit-push --push-only --keep-checkout --scan-secrets --path <checkout> scans what the local commits add, merges in memory, pushes the merge, refuses on a conflicting file and never moves the checkout (the refusal's fix fills in the real path and counts the local commits). Then retry gbrain sources refresh <source>, which fast-forwards to the merge. gbrain sources reclone <source> replaces the checkout instead and drops the local commits. With sources.refresh_publish_diverged unset on a worktree whose Git durability is on, or set to true, the refresh runs that publish itself, in a child process that skips the pre-push hook, and then fast-forwards; that child first scans what the local commits add (messages, added lines, merge resolutions) and refuses publish_secret_found naming the file, line and rule (never the value) when one looks like a secret, and unset with durability not on refuses naming gbrain sources writer git-durability <source> --enable; a conflicting file then refuses integrate_conflict (with gbrain.quarantine on, the remote's version is published instead, this machine's is kept under refs/gbrain/quarantine/, and the refresh says so), and an uncommitted edit to a file the upstream changed refuses refresh_dirty, both with nothing pushed. The setting never publishes over a rewritten upstream: when the checkout holds a commit the upstream held before but no longer contains (a force-push), or gbrain has no record of the upstream before the fetch, the refresh still refuses refresh_diverged and the user decides.
refresh_dirty refresh_dirty Uncommitted or untracked files overlap the incoming upstream changes (the first 20 are named), or git merge --ff-only refused for the same reason. HEAD did not move. The merge runs under the checkout's commit lock, so a gbrain git commit-push in progress is waited out (#8117); a lock held past its wait refuses as commit_lock_busy, and another git process holding .git/index.lock refuses as git_index_locked after brief retries. Both are retryable. Uncommitted files outside the incoming changes do not refuse; they are kept and listed as preserved_uncommitted. Commit or discard the named paths, then retry. Check gbrain sources writer status <source> --json first: a pending Git effect may be about to commit a gbrain-published file.
sync_in_progress sync_in_progress A managed sync of one of the checkout's sources has an unfinished cursor. Moving the checkout now would strand it, and the refresh never waits on a sync. gbrain repair frontmatter --apply refuses the same way while an unfinished cursor still names a selected file. Run the printed gbrain sync --source <source> --no-pull ... resume command (it keeps the cursor's options), then retry (for a repair, preview again and approve the new hash).
refresh_in_progress refresh_in_progress Another refresh of the same checkout is active and its process is still running (the message names its holder's pid and host when the active refresh row is already readable), or a command that changes which sources share the checkout (sources add, remove, archive, restore, reclone) ran while one was active. A refresh whose process died is not a reason to refuse: the next refresh on the owner host finishes it first (--dry-run does not, so it still refuses while the orphan stands, and neither does a refresh that cannot read the checkout's HEAD: it leaves the orphan as it is and refuses until git can read HEAD again; writer status then names git -C <checkout> status instead of the next refresh). A refresh whose holder is recorded on another host, or whose lock file this host cannot open, is never taken over either: writer status shows its liveness as unknown (its next names the host to run on), and gbrain sources refresh <source> --resume on the owner host finishes it once that host's refresh is known to have stopped. Pending publication or topology recovery on the checkout refuses refresh_recovery_required first. An interrupted refresh that needs a reset decision refuses refresh_recovery_required instead. Wait for the running refresh, or check it with gbrain sources writer status <source> (liveness, holder). gbrain sources refresh <source> --resume finishes an orphaned one now; then retry the source command with the same request ID.
refresh_drain_timeout refresh_drain_timeout Queued writes or Git effects on the checkout did not finish within --wait-drain (default 60 s; sources.refresh_drain_wait_ms; GBRAIN_REFRESH_DRAIN_WAIT_MS). The counts are in the message. The fence was lifted and HEAD did not move. Retry, or wait longer with --wait-drain <seconds>. Inspect what is queued with gbrain sources writer status <source> --json.
refresh_lock_timeout refresh_lock_timeout The refresh fence locks the brain, worktree, source and refresh rows with a 5 s lock timeout, and another database transaction held one of them longer. why lists the five oldest open transactions in this database holding locks on those tables (pid, application, state, how long the transaction has been open). They are candidates: the blocker may not be among them, because Postgres does not show which row each one holds. It never repeats their SQL, and says so when that lookup failed or took longer than 3 s. HEAD did not move: no fence was set, or the draining refresh was aborted. When the same holder also blocked that abort, the refusal says the row stays draining, and the next gbrain sources refresh <source> resumes it. Retry gbrain sources refresh <source>. If it repeats, a transaction holding one of those rows is stuck: why lists the oldest candidates, so confirm the blocker on the brain host before ending any transaction.
refresh_sync_timeout refresh_sync_timeout Reported per source in a refresh's sync_blocked, not as a refusal: the source's managed sync committed nothing within its share of the refresh sync budget (each member gets an equal share of what is left; sources.refresh_sync_budget_ms, GBRAIN_REFRESH_SYNC_BUDGET_MS, default 5 min), for example because no consumer claimed its write. The message names that write and its state. The checkout is at the upstream commit, the refresh completed and released its lock, and the source is behind until its next sync. A sync stopped by the drain's own rules is reported with that stop's code instead (drain_stalled and the others). Run the resume command (gbrain sync --source <source> --no-pull). If it stalls the same way, check the write it names with gbrain sources writer status <source> --json.
refresh_source_changed refresh_source_changed HEAD moved (an outside commit or checkout, gbrain's own commits the upstream does not hold yet, or gbrain's own commits under an upstream branch that changed while the refresh waited; the upstream is compared only when HEAD moved), or the checkout's ownership or set of sources changed, between the precheck and the merge. Nothing was merged and the fence was lifted. When HEAD moved or work reached the checkout after the drain check, the run already retried once from a fresh precheck, and the message names why that retry was refused too. Retry gbrain sources refresh <source>.
refresh_recovery_required refresh_recovery_required Publication or source recovery is pending on the checkout, or a refresh was interrupted and HEAD is neither the commit it started from nor the verified upstream commit. (A commit that lands on the upstream commit right after the refresh's own merge is not this case: the refresh records the merge and syncs it. Nor is one that lands on the start commit right before the merge: git refuses the fast-forward and the refresh ends refresh_source_changed; if its process dies before that, recovery aborts the refresh the same way when the checkout's reflog shows HEAD never reached the upstream commit.) Writes to the checkout stay refused until it is resolved; gbrain never adopts a HEAD it cannot verify. gbrain sources writer status <source>, then gbrain sources refresh <source> --resume. When HEAD is unverified the fix names both ways out: reset to the start commit and run --abandon, or reset to the upstream commit and run --resume. Resetting is destructive, so ask the user first. Writer status reads HEAD and names the one step left when HEAD already sits at one of those commits: --resume at the upstream commit, --abandon at the start commit when no member source has synced past it. When one has (its last_commit is set and is neither the start commit nor an ancestor of it; a commit git cannot find counts too), --abandon refuses with this code and changes nothing, because the next sync would roll that member's pages back; --resume refuses too, and both name the one way out that keeps those pages: the fix (next: ask_user) previews with git -C <checkout> status --short, fast-forwards the checkout with git merge --ff-only to the commit the members synced (the upstream commit, or a later one a member already synced; it keeps uncommitted edits and refuses if one overlaps an incoming file), then runs --resume. When git refuses, the fix names a hard reset to that commit instead (destructive: it discards local commits and uncommitted edits not in that commit). --resume finishes a recovery_required refresh whose HEAD is the upstream commit or descends from it, unless a member synced a commit on this refresh's line (or one git cannot place) that HEAD does not contain; then it refuses with the same fast-forward fix. A member also counts as synced past the start commit when a managed sync imported or deleted a page for it after the refresh began, even though its last_commit is still the start commit (a pass stopped by its budget before its stamp), so the database is never left ahead of the checkout. --abandon of a recovery_required refresh checks the members and lifts the fence holding every member's drain lease: while a sync pass still holds one it refuses sync_drain_lease_held and changes nothing; retry once that pass ends. At a HEAD that is the upstream commit or descends from it (and holds every member's commit), --abandon refuses refresh_in_progress naming --resume, which finishes the refresh in one run. When the members' commits do not form one line (two members synced different commits past the upstream commit), no fast-forward keeps every member's pages: the refusal and writer status name each commit, and the fix (next: ask_user) is git -C <checkout> merge --no-edit <commits>, which joins them in one commit (on a conflict git stops with the conflicts in the checkout), then --resume. When git cannot place a member's commit (a missing object, an unreadable checkout, a git timeout), the refusal names that commit instead and its fix fetches (git -C <checkout> fetch --all --no-tags), then --resume names the way out; if no remote holds the commit any more, ask the user. Rolled back on purpose: an operator who reset the checkout to the start commit to reject an upstream change keeps git the parent by moving forward instead: fast-forward as the fix names, commit git -C <checkout> revert --no-edit <the unwanted commits> on top, then --resume; the refresh completes and the next sync removes those pages through history. There is no flag that abandons past a synced member. Writer status read on a host that is not the owner names no step for such a refresh (actor: host_admin): whether --abandon is safe depends on the owner's checkout, so run writer status on the owner host.
worktree_refreshing worktree_refreshing A write, or a managed sync started by a cycle or another command, reached a checkout while a refresh is draining or merging it. It was not saved. detail is retry_after_ms=<n>, estimated from the refresh itself: the median duration of the worktree's last completed refreshes minus how long this one has run, never below 15 s while it syncs or 2 s in its other phases (so a refresh of several minutes is never answered with a 1 s retry). The message names the phase, how long the refresh has run and typically takes, and the CLI's human output ends with one line, Nothing was saved; retry the same command in about <n> s (retry_after_ms=<n>)., which survives ` tail -1. Writes to database-only memory are not affected. An interactive write (CLI, MCP) waits out the fence for up to 10 s, or its explicit wait_msif lower, before this refusal; a background write is refused at once. The refusal isretryable, its fix.nextiswait, and the CLI exits 1; the memory verbs keep their frozen unavailablecode withcanonical: worktree_refreshing. With persistence.refresh_barrier` on, a single page or memory write waits behind the refresh instead (deferred writes).

A refresh is recorded in persistence_worktree_refreshes and survives a crash. When the owner restarts it finishes the deterministic steps on its own: an interrupted drain or a fence with HEAD unchanged is abandoned, and a merge that already reached the verified upstream commit moves on to syncing. gbrain sources refresh <source> --resume runs the remaining syncs. A refresh whose process died (for example a container replaced mid-refresh) does not wedge the checkout: the owner completes a syncing one once every source has synced to its target, and the next plain gbrain sources refresh on the owner host finishes any other one the same way --resume does, then refreshes. A refresh whose process is still running is never taken over. gbrain sources writer status and gbrain sync status show who holds each refresh and whether it is orphaned. With --json, a refresh refusal that carries a structured next step (refresh_diverged's consent-gated publish, refresh_in_progress's writer status read, a git read failure) prints it as the v1 fix object (argv, next, actor), with the prose in suggestion; any other refusal keeps the stored command string in fix. Doctor reports worktree_refresh_stuck for a refresh active longer than 15 minutes, with the resume command.

Deferred writes

With persistence.refresh_barrier on (gbrain config set persistence.refresh_barrier true, or GBRAIN_REFRESH_BARRIER=1; off by default), a single page or memory write (put, edit, rename, delete, append, remember, forget) that reaches a checkout while a refresh is draining, fenced, merging or syncing it is accepted and waits for the refresh instead of being refused worktree_refreshing:

  • The caller gets a pending receipt at once: the CLI exits 10 (write_pending); MCP answers isError: false with status: "pending", request_id, receipt (state queued), deferred: { refresh_id } and next (get_write_request / gbrain write-request <id>). Replaying the same request ID returns the same receipt.
  • When the refresh ends, the owner publishes the write in arrival order. If the refresh changed a file the write would publish, the write ends conflict with revision_conflict naming the refresh and the files, and nothing is applied: a refreshed page is never overwritten. Read the page again and submit the change with a new request ID. A credential that no longer grants the write ends it permission_denied.
  • A write whose refresh is still unfinished after persistence.refresh_barrier_max_wait_ms (default 15 minutes) ends failed with refresh_barrier_expired, nothing applied. Check the refresh with gbrain sources writer status --source <source> --json, then submit again with a new request ID.
  • A refresh in recovery_required holds writes the same way: they wait until the refresh is resumed or abandoned, under the same wait limit. There is no per-refresh cap: deferred writes count against the journal's ordinary outstanding and byte limits, like queued ones.
  • A put_page, capture, remember or add_timeline_entry whose page file holds a committed change managed sync has not imported yet (pending_import) also waits instead of being refused: the receipt stays pending with deferred: { pending_import: true }, and once the import lands the write is prepared again against the imported page. A remember or add_timeline_entry applies on top; a put_page with expected_revision ends revision_conflict when the import moved the page; a blind (force) put_page or a capture lands over it, and its receipt (supersedes), its commit trailer (gbrain-supersedes: <path>: revision <id> from <commit>) and the commit ledger name the imported revision and commit it replaced, both still in page history and Git. A write whose import has not landed within the wait limit of its hold, or that has waited four wait limits (at least 4 hours) since its admission across repeated holds, ends failed with pending_import_expired, nothing applied: check gbrain sync status --source <source> --json, then read the page again and submit with a new request ID. A remember ends as the pending_import refusal did instead: the fact is kept and the caller does not save it again. When it named its entity, the first sync that imports the file replays it; otherwise gbrain repair failed-writes --source <source> lists it for a person to replay. A write keeps the refusal when a live consumer on the owner host runs a release that cannot claim a held write.
  • A refresh that ends without completing (aborted, abandoned, or rolled back after its process died) never imports the commit its fence kept sync from importing, so the next gbrain sources refresh run on the owner host (the same run, --resume or --abandon, or the next tick, even one refused refresh_diverged) ends by running the managed --no-pull sync of each member behind the checkout HEAD. A write held for that import is then prepared again as above in that run, instead of waiting for a later refresh.
  • A write that waited behind a refresh or for an import ends revision_conflict, nothing applied, when a later write to the same page committed before it, which a consumer from an older release can cause by claiming the later write first. Read the page again and submit the change with a new request ID. A waiting remember or add_timeline_entry is the exception: it still applies on top.
  • Still refused as before: batches (put_pages, remember with items), jobs, skill bundles, and any brain where a live consumer on the owner host runs a release without the barrier. Repo-less brains and database-only sources never wait.
  • gbrain sources writer status --json shows deferred: { count, oldest_age_ms, refresh_id } on each active refresh.
  • Before installing an older release, turn the barrier off and wait for gbrain upgrade --check-downgrade to exit 0. It exits 3 with downgrade_blocked_deferred_writes (count and oldest age) while any write admitted deferred has not finished, waiting or already claimed, because an older release never drains them safely. A released write publishes only when a gbrain process runs the write consumer on the worktree's owner host (gbrain serve, gbrain jobs work, or any gbrain write or sync import there); polling gbrain write-request only reads its receipt, so on a host with only cron jobs it waits for the next run.

Managed sync drain stops

gbrain sync on a managed brain keeps going until the source's cursor is done (see catching up a large backlog). When it stops early, the run ends in one outcome: resumable (exit 0, safe to rerun the same command) or blocked (exit 1, needs a fix first). --json carries outcome, drain.stop_reason and next: { command, safe_to_loop, retry_after_ms, eta_seconds, rate_pages_per_min, why, docs }. Run next.command; loop on it only when next.safe_to_loop is true.

Say to your agent: "Catch up my managed brain's sync backlog and tell me how long it will take."

Stop reason Code Outcome What it means Recovery
deadline, terminated writer_pending resumable --timeout, --hard-deadline, Ctrl-C or the run deadline stopped the drain, or a sync job reached its own deadline (its timeout_ms less a 60 s reserve). terminated: a SIGTERM or SIGHUP reached gbrain sync during a managed pass, which recorded its stop before the run exited 143 (129 for SIGHUP). Accepted page writes keep their request IDs and the cursor is intact. Rerun next.command (the same options). It resumes where the last run stopped. A sync job that queued a follow-up (continuation_job_id) names it in next instead: watch it, don't start a second sync beside it.
drain_stalled drain_stalled blocked The awaited page write and the oldest unfinished write on its checkout made no progress for the whole stall window: no committed receipt and no step advance. A lease renewal is not a change: the detector keys on the head claim's phase and step. With a live owner on this host, the drain does not stop at the allowance (the preparation budget plus 30 s): from there it prints stalled <N>s on <step> with the owner's pid and kind every 10 s and keeps going, because the owner's own budget frees the root by persistence.preparation_ceiling_ms (600 s) and the next pass holds the entry. It stops drain_stalled only when the ceiling passes without the root being released, or when the owner's persistence_consumers row reads wedged (restart_required, or a root barrier older than the ceiling); the stop then carries cause: owner_wedged_here, the owner {kind, pid, nonce}, retry_after_ms (the time left to the ceiling, 0 once past), next.safe_to_loop: true while the ceiling is ahead and next.fix.next wait before it, tell_user_to_run (restart the named pid) after it. A lapsed claim (owner_missing) stops at once, unless this host owns the checkout and a live full consumer exists, which gets exactly one more window. Other causes: preparation_overdue / publication_overdue (a live owner elsewhere past its allowance) and no_progress (an unstamped head). A pass that never returns is stopped from inside (drain.stall.in_pass: true, the same rules whether or not the drain prints progress): a head claim live in publishing past persistence.publication_ceiling_ms (default 300 s) stops publication_overdue, and its next says to restart the process that owns the publication, because an unfinished publish can hold its locks until it settles and nothing reclaims it for you; a pass that admitted nothing and left no unfinished request for 5 minutes stops no_progress with the step it was in (freeze, waiver_run, admission, await_receipt) and the last statement label, which is what a transaction-mode pooler that never answers a round trip looks like (older builds named this cause no_admission; it is retired, and a receipt carrying it means the same). The pass returns when the run's final checkpoint commits: the tail after it (planner statistics, link extraction for the imported pages) runs after the drain lease is released, outside this governor, bounded at 5 minutes; the checkpoint's own transaction records it as owed, so a process that dies before it leaves it for the next sync of the source, and a failed or cut-short tail keeps the run synced with a [gbrain notice sync_tail_degraded] whose fix is gbrain extract --stale --source-id <id>. The owner process bounds its own publish the same way: past the ceiling the claim reads waiting_on: publication_deadline, a Postgres publish transaction idle past it is ended by the server (nothing commits), 30 s later a Postgres publish still running is cancelled (its connection is discarded, nothing commits, and the write is queued again), and a publish that still has not settled 35 s after the ceiling makes the owner report restart_required (its heartbeat row carries restart_required, which the drain reads as owner_wedged_here; the consumer status lists it under stuck_publications); restart that process. drain.stall carries phase, step, waiting_on, cause, the owner and whether this host owns the checkout. gbrain sources writer status --source <source> --json: its next_action says whether to wait (retry_after_ms) or which pid to restart. Before the ceiling, rerun next.command after retry_after_ms (safe in a loop). Past it, or with a wedged owner, restart the named owner process (gbrain serve, the jobs worker or autopilot) on the brain host, then rerun next.command; the held entry needs gbrain sources retry-held <source> afterwards. When this host is not the owner, make sure the owner's gbrain serve is running.
database_contention database_contention blocked (or an error) Three consecutive passes hit database contention, a statement timeout or a dropped connection, or reading the awaited write's state failed (an authentication or permission failure stops at once). The drain retries transient failures with backoff before giving up. Accepted writes keep their request IDs. Fix database access (gbrain engine status --probe), then rerun next.command.
recovery_required, owner_unavailable, unexpected_file_bytes, unexpected_staging_bytes recovery_required blocked The checkout's writer needs intervention before more pages can publish: interrupted publication recovery, no live owner, or unexpected bytes in the file or staging area. gbrain sources writer status <source> and the fix it prints. Unexpected bytes are the user's edits; ask before discarding them. Then rerun next.command.
blocked_by_failures blocked_by_failures blocked A page write failed terminally. managed_write and failures name the page and cause. Rerunning without a fix returns the same failure. Fix the cause, then run next.command (the plain sync with the same options). Ask the user before skipping content.
preparation_abandoned preparation_abandoned resumable A write this process's own writer holds was still preparing past its allowance (its budget plus 30 s, never more than the ceiling persistence.preparation_ceiling_ms plus 30 s) and the process cannot cancel it, so the sync exited to end it. The cursor and accepted writes are intact; drain.stall names the step (stall.step, stall.waiting_on). Exit 0. Rerun next.command (safe_to_loop is true). The next pass holds the entry as preparation_stalled if it stalls again; gbrain sources writer status --source <source> --json shows what it was stuck on.
preparation_systemic preparation_systemic blocked The run's breaker tripped: more preparation_stalled receipts than a source should hold (the GBRAIN_SYNC_HOLD_ESCALATE_COUNT / GBRAIN_SYNC_HOLD_ESCALATE_PCT rule over this run's screened imports) or five stalled entries in a row with no page committed between them. The run stopped with one diagnostic instead of holding every file: the write owner, not the files, is the likely cause. breaker carries the rule, the counts, the last step and the fix; exit 1. gbrain sources writer status --source <source> --json, fix what it names or upgrade gbrain, then rerun the same sync: it re-freezes the stopped entry under a fresh request and schedules the files this run held for a re-screen.
write_capacity queue_capacity blocked The sync could not admit its next write for the whole no-progress window (30 s) because other writers' requests held the outstanding-request cap of its write principal (persistence.limits.principal_outstanding, default 100; the brain cap persistence.limits.brain_outstanding, 1000, works the same way): on one host the CLI sync and a maintenance run (fact-fence adoption, dream) share the local_cli principal, so a long adoption queue leaves no room for a sync write. Nothing failed and the cursor is intact: the drain retried the admission with backoff while they settled, printing waiting for write capacity (N outstanding of M), and stopped only when the window passed. drain.capacity carries the counts and the wait; exit 1. A cumulative cap (permanent request IDs, receipt bytes) is a different refusal: it names its config key and stops at once. gbrain sources writer status --source <source> --json lists the outstanding requests (read-only). Let them finish, or raise the cap (gbrain config set persistence.limits.principal_outstanding 200), then rerun the same sync; it resumes where it stopped.
connection_lost connection_lost blocked The database connection dropped three times in a row (write ECONNABORTED, ECONNRESET, ETIMEDOUT, EPIPE: a pooler closing the socket mid-statement) with no page committed between the drops (#6340). Each drop was reconnected and retried after 5, 15 and 45 s; a drop that then moves data is not reported at all. Nothing is recorded against the source: the cursor and its frozen manifest stand, and drain.connection carries the count and the last error text (never a URL). Exit 1. Check the database and pooler (gbrain doctor --json), then rerun next.command (safe_to_loop is true, retry_after_ms 60 s): it resumes at the stored cursor without re-freezing the manifest. Runbook: sync unblock.
capacity_paused capacity_paused resumable The run passed its capacity preflight, then a cumulative write cap refused its next admission (write_quota_exhausted) or, for a background sync, the pause line did (write_capacity_backpressure): another writer used the room the preflight counted on. Nothing failed; the cursor and every accepted write stand, and drain.capacity_pause names the refusal and its config raise. Run the gbrain config set the report names on the brain host (request ids never free; receipt bytes also free as receipts compact), then rerun the same gbrain sync. Verify with gbrain doctor --only persistence_capacity --json.
drain_stalled with cause: head_blocked drain_stalled blocked The queued write at the head of the source cannot be claimed by any consumer, and its blocker needs an operator (#6543). drain.stall.blocked_by names the predicate, its ids, state and owner: refresh_fence (a refresh left the checkout fenced, merged or recovery_required and no refresh process holds its lock), zombie_publication (a running request ahead of the head is held by a process that reports restart_required), or effect_recovery with state unexpected_file_bytes (a fact-withdrawal mirror's page file was edited while the mirror was publishing, so its forward-only recovery refuses to overwrite it), or request_recovery with state unexpected_file_bytes (a page write's file, or a file of a shared-skill bundle, was edited while it was publishing, #6650; this also covers a head that is itself that recovering write). For both, blocked_by.file names the page and path (an effect's also names its withdrawal request). effect_recovery or request_recovery with state recovery_version_unsupported is a record a newer gbrain wrote, which no recovery here finishes. A recovery stuck on unexpected_staging_bytes is not classified yet and still waits out the window. The drain stops after one governor tick of confirmation instead of the no-progress window. Live blockers (root_hold, a foreground publication; lease, a lapsed claim the next consumer reclaims; withdrawal_mirror, an effect_recovery or request_recovery that can still finish, worktree_owner) never stop it: the stall line names them as blocked_by= beside consumer= and the drain keeps waiting. claimable here is read for the head itself and prints unknown when the probe could not read it. Run next.fix: refresh_fence resumes the refresh (gbrain sources refresh <source> --resume, which lifts the fence or names why it cannot); zombie_publication tells the host admin to restart the named process; effect_recovery runs the gbrain repair stuck-recovery --source <source> --request-id <request> preview, whose only choice (--keep withdrawn, the user's to apply) backs the edit up and writes the withdrawn version; or the user restores the committed version, never deletes the file, and redoes the edit without the forgotten fact; request_recovery runs the gbrain repair stuck-recovery --source <source> preview, and the user either keeps one version through it or undoes the edit. Then rerun the sync. gbrain sources writer status --source <source> --json names the same blocker for every queued head and, only when the caller may cancel the blocking request, gbrain cancel-write-request <request_id>; recovery_version_unsupported tells the user to run gbrain upgrade on the owner host.
drain_lease_held sync_drain_lease_held resumable Another process holds the source's drain lease (#6712): one managed drainer per source, and that holder (a serve, a sync job, the dream cycle, another terminal) is still committing pages. gbrain sync follows it within its own --timeout and run deadline, printing the holder (kind, pid, host, gbrain version) and the pages it commits (every 10 s on a terminal, 60 s otherwise), and takes the lease when the holder releases it. This code means the budget ended first, or the lease moved to another process mid-pass (lost); nothing this run admitted is lost and the cursor is intact. --no-delegate never skips the lease. drain.lease_held.holder reuses the drain's owner fields: kind, id, host, pid, started_at, last_heartbeat_at, version and progress (committed, last_committed_at, last_progress_at); next.retry_after_ms is 60 s and next.safe_to_loop is true. Exit 0. A cron that runs gbrain sync every few minutes beside a serve exits 0 here on each tick while the serve works. Rerun next.command after next.retry_after_ms, or let the holder finish. gbrain sources refresh <source> --abandon refuses with this code too while a member's sync pass holds its lease (nothing changed); retry it once the pass ends. Ctrl-C while following stops only this run; the holder keeps going. A holder that commits nothing for 5 minutes is not reported here: the run stops drain_stalled instead.
drain_stalled with cause: no_progress and stall.lease_holder drain_stalled blocked The process holding the source's drain lease committed no page and saved no cursor for 5 minutes, so following it would exit 0 forever (#6712). drain.stall.lease_holder names it with the fields above; the lease itself is renewed by a live process, so a wedged holder keeps it. A holder that died lets its lease lapse within 2 minutes and the next run takes over without this stop. Exit 1, next.safe_to_loop false. gbrain sources writer status --source <source> --json (read-only) shows what the holder is waiting on. Stop or restart the named process; when it is gone but its lock row remains, gbrain sync --source <source> --no-pull --break-lock releases a lock whose pid is dead (--force-break-lock skips the liveness check: only when you know the holder is gone). Then rerun the same sync.
not_converged not_converged resumable The live pass (#6712 PR 4b) used its rounds without the level settling: another writer kept changing the checkout or the database while it ran. Everything it admitted stands and nothing is held for it; the pass row counts consecutive such passes (not_converged_streak). Rerun the same gbrain sync (next.safe_to_loop is true). After three consecutive not_converged passes next turns to report (safe_to_loop false): run gbrain sync status --source <id> --json and gbrain doctor --json and report what keeps changing. Exit 0.
admission_paused admission_paused resumable sync.admission is imports_only or classify_only, so the pass admitted only what it allows (or nothing) and stopped; a destructive write paused at publication is completed cancelled with admission_paused. Nothing failed. Restoring admission is the owner's decision: gbrain config set sync.admission normal (next.fix is tell_user_to_run; never run automatically). The next sync continues. Exit 0.
grant_scope grant_scope blocked The pass ran under a grant that covers only part of the source, so it admitted what the grant can see and cannot stamp the source. On the owner host run gbrain sync --source <id> --no-pull (next.fix is tell_user_to_run), then verify with gbrain sync status --source <id> --json. Exit 1.
reconcile_host_required reconcile_host_required blocked A remote caller's pass admitted what it could; the rest needs the owner host, because remote callers never write holds, markers, keep_db writes or the stamp. On the owner host run gbrain sync --source <id> --no-pull (tell_user_to_run), then verify with gbrain sync status --source <id> --json. Exit 1.
reconcile_read_incomplete reconcile_read_incomplete blocked A Git listing the pass reads (ls-tree, ls-files, diff-tree) did not finish cleanly, so the pass classified and wrote nothing. Check the checkout with git -C <dir> status; report it with gbrain doctor --json if it repeats (next.fix is report). Exit 1.

Unbound sources on Postgres

A source with a checkout path (local_path, or sync.repo_path for the default source) normally publishes every page write to a markdown file in that checkout, through the source's canonical owner. PGLite claims that owner automatically on the first write. Postgres does not, because several hosts can share one Postgres brain and only one of them may own the files. Neither does PGLite for a source writer activate listed under database_only_sources (a rooted source with no owner on a brain whose sync.write_through was off, #6449; the list is the config key persistence.database_only_sources, which deactivation clears): turning the setting back on never starts an unreviewed claim there. Until someone binds the source, page writes to it refuse with owner_unavailable and detail: unbound_source. The refusal is a configuration state, not a transient one: it renders retryable: false and a fix with next: ask_user, so an agent never retries it.

Classic mode (managed persistence not activated). This is the normal state of a self-hosted Postgres brain that never ran gbrain sources writer activate, and of any brain after gbrain sources writer deactivate. In classic mode the checkout is the source of truth: gbrain reads it and does not write files into it. Page writes through put_page, capture, delete_page, restore_page, revert_version, add_tag, remove_tag, add_timeline_entry and the takes_* tools refuse with unbound_source, and so do remember about an existing entity page and forget or forget_fact of a claim that a canonical file carries (their frozen code stays unavailable, with write_error: owner_unavailable and the same detail and fix; a claim that only database-only pages carry is still withdrawn, database-only). What works:

  1. Write the file, commit, sync (the classic write path). Write or edit <checkout>/<slug>.md, check generated frontmatter with gbrain frontmatter validate --stdin --path <slug>.md, commit it with gbrain git commit-push --path <checkout> -m <msg> -- <slug>.md, then run gbrain sync --source <id>. Sync imports commits; --working-tree imports uncommitted edits for one run. Delete the file, commit the deletion the same way, sync. Tags and timeline entries are frontmatter and ## Timeline lines in the same file.
  2. Database-only pages, if the user accepts that new pages never reach the checkout, its git history or file backups: gbrain config set persistence.unbound_write database_only (below). It never covers pages that came from files.
  3. Leave classic mode (a brain-wide decision for the user): claim the source and activate managed persistence (topologies). A claim without activation blocks classic gbrain sync of that source, so never claim to get one refused write through.

What the agent tells the user. An agent with a shell on the brain host asks once, then uses path 1 itself and reads the page back. A remote agent (MCP) cannot write the checkout; it says: "Your brain is in classic mode, so I can't save pages directly. Save it as <slug>.md in the <id> folder, commit it, and run gbrain sync --source <id>. Or I can explain the two other options: database-only pages, or managed mode." It does not retry the write.

Managed mode, or a gbrain-owned checkout. The suggestion names both ways out with the real source filled in:

  1. Bind the source on the host that holds the checkout. Run gbrain sources writer status <source> --json and note admin_state, then gbrain sources writer claim <source> --path <checkout> --admin-intent writer_claim --expected-state <admin_state>. If an operator has locked writer administration, ask them to unlock it first. Read topologies before claiming a source that other hosts write to.
  2. Allow database-only writes with gbrain config set persistence.unbound_write database_only (the default is refuse; no other value is accepted, and the key can only be set on the brain host). Every page write to a page with no recorded canonical file (a new page, or one with no stored source path) then writes to the database only: put_page, capture, delete_page, restore_page, revert_version, add_tag, remove_tag, add_timeline_entry, the takes_* writes, and a remember (or loop-close retirement) whose fact is fenced into that page's database body. Its result says write_through: { written: false, skipped: "unbound_source" } with a warning. Pages written this way stay database-only: binding the source later does not materialize them into canonical files, later writes keep them database-only, and sync never deletes or overwrites them. To restore the refusal, run gbrain config unset persistence.unbound_write.

The opt-in never applies to a page that came from a canonical file (it has a stored source path). An edit there could be lost on the owner's next sync, so it keeps refusing with only the bind option. revert_version is also judged on the version it writes: reverting to a version recorded while the page had a canonical file refuses the same way (a version an older gbrain recorded without that information counts as file-less).

If the source is bound after a database-only write was accepted but before it was published, the write fails with the same reason and nothing is written; read the page again and resubmit with a new request ID. If a canonical file appears at the path of a database-only page after binding, sync stops for that file with source_changed and reason unbound_source; neither copy is overwritten and the database page stays served. Rename or remove the file, commit, and sync again. Or settle the pair: gbrain sources reconcile <source> <slug> --preview and decide take_file to keep the file, or preview gbrain repair file-drift --source <source> --slug <slug> --prefer database to keep the database copy (it names the file's commit, and its apply needs the user's consent).

gbrain doctor reports the unbound_source check: the number of such pages per source. While the source is unbound it is ok and prints the bind command; after binding it warns, because those pages sit outside the canonical files. There is no command yet that turns them into files; to move one, save its content under a new slug and delete the database-only page.

Foreign ownership marker

When a host claims a source checkout, gbrain writes two private ownership markers: .gbrain-owner.json inside the checkout and .gbrain-owner-<sha256 of the path>.json beside it. Both record the brain id and the worktree id they belong to. A claim of a checkout whose markers name another brain refuses recovery_required ("The physical checkout identity changed or belongs to another owner"), because removing a live brain's marker to claim its files would let two brains write the same checkout.

A marker left behind by a brain that no longer exists (a PGLite brain later moved to Postgres with gbrain migrate, a gbrain init that was redone, a database dropped by hand) refuses the same way, and the refusal does not say which file or which brain. gbrain doctor reports the foreign_ownership_marker check for every source checkout and owner binding on this host: the marker's path, the brain id it records, and whether this brain knows the worktree. The check is read-only and runs only on the brain host.

Clearing it is the operator's decision, in this order:

  1. Confirm with the user that the recorded brain is retired: it was moved into this database, or it was deleted on purpose. gbrain doctor --json on the old brain's home, if it still exists, shows its brain_id.
  2. Remove exactly the file doctor names on the brain host. Do not remove a marker of a brain that is still in use; transfer ownership with gbrain sources writer transfer prepare|accept instead.
  3. Claim again: gbrain sources writer claim <source> --path <checkout> --dry-run, then the printed apply command.

A marker of this brain that other users can read (mode 0644 after a recursive chmod) is reported by the same check with its mode and the exact chmod 600 '<path>' that restores it, and every write to that checkout refuses ownership_record_not_private until then. Do not remove such a marker: it belongs to this brain.

Secret scan refusals and redaction

GBrain runs one secret scanner in several places. Depending on where a credential-shaped value turns up, it blocks a push, leaves an entry out of compiled context, skips a relay, or is replaced in output with a <REDACTED:pattern> token (for example <REDACTED:url_credentials>). The stored page never changes: redaction applies to what a caller receives, not to your files or database.

Where What happens What to do
gbrain sources push Refused with blocked_secrets, exit code 5. Nothing is committed; the index is reset to HEAD and files on disk are untouched. Remove a real credential and rotate it. Allowlist only a reviewed false positive (below).
gbrain bootstrap verify, gbrain bootstrap repo The secret-scan check fails, or the first push stops before anything is committed or pushed. Each finding shows its file, line, pattern, fingerprint and the version that added the rule. Same as push.
Compiled context (gbrain compile-context) The entry is left out. One line on stderr names the page, the pattern and the fingerprint, never the value. Remove the value from the page, or allowlist a reviewed false positive.
Memory relay at compaction The receipt and relay are skipped for that compaction window only; the checkpoint is kept. A content-free line (reason: secret_scan_refused, pattern, fingerprint, hint) goes to ~/.gbrain/integrations/hooks/heartbeat.jsonl. Nothing to run; the next window is scanned again. Remove the value from the transcript source if it keeps recurring.
Retrieval output The value is replaced with <REDACTED:pattern>; everything else in the result is unchanged. Nothing. Read the page on the brain host if you need the value (see what stays raw below).
Page reads Not redacted. See what stays raw by design.
Configured providers Not redacted yet. See what stays raw by design.

An allowlist entry stops pushes and compiled context from refusing a finding. It does not turn off retrieval redaction: search and recall still replace an allowlisted value.

Shapes this scanner catches

Vendor key prefixes (OpenAI, Anthropic, Voyage, GitHub, GitLab, Slack, AWS, Google, Stripe, SendGrid, Twilio, Supabase, npm, Hugging Face, DigitalOcean, OpenRouter, Groq, xAI, Perplexity, Replicate, gbrain tokens), JWTs, Bearer tokens, private keys, database URLs carrying a password, http(s) URLs carrying a password (url_credentials) and Authorization: Basic credentials (basic_auth). A private key is caught even when a snippet or chunk cut off its BEGIN or END line: the key body lines are redacted along with whichever fence is present.

Search chunks never hold key material. A page whose text contains a private key is chunked from a copy in which each key is replaced by <REDACTED:private_key_pem> (line breaks kept, so positions do not shift), and evidence delivery cuts window, section and page text from the same copy. A chunk from the middle of a long key, with neither its BEGIN nor its END line, therefore carries the token instead of key lines, and key material never reaches the embedding provider. The stored page is unchanged. Pages indexed by a gbrain older than v0.60.31.0 that contain a BEGIN or END … PRIVATE KEY line are withheld from search until the upgrade re-chunks them, without provider calls; gbrain doctor reports them as credential_projection_pending until then, and gbrain embed --stale embeds the new chunks when you choose to. Key material with no BEGIN or END line anywhere on the page, and keys inside image OCR text, are not projected.

Retrieval output, transcript import, hooks and the memory relay also run the assignment rule (high_entropy_assignment): a value of 12 or more characters with at least one digit and enough randomness, assigned to a key such as password, token, secret or api_key. Pushes and compiled context do not run that rule, so a plain DB_PASSWORD=... line never blocks a push.

Placeholder passwords in URLs are skipped: <password>, ${VAR}, $VAR, and all-* or all-x masks. A URL with a user and no password, and paths that only contain @ (https://registry.example/@scope/pkg), are not credentials.

When a push is refused

PUSH BLOCKED — secret scan findings (nothing committed):
  notes/deploy.md:12 [url_credentials] clone <REDACTED:url_credentials>git.example.com/team/repo.git
    fingerprint: sha256:<16 hex characters>
    rule [url_credentials] blocks pushes since gbrain v0.60.31.0
    allow this finding: printf '\n%s\n' sha256:<16 hex characters> >> '/home/you/brain/.gbrain-scan-allow'
Remove a real credential from the file (and rotate it) first. Allowlist only a reviewed false positive
with the "allow this finding" command above (it appends to '/home/you/brain/.gbrain-scan-allow'), then retry:
  gbrain sources push --path '/home/you/brain'
Docs: https://github.com/garrytan/gbrain/blob/master/docs/guides/write-refusals.md#secret-scan-refusals-and-redaction

Each finding carries:

  • fingerprint: sha256: plus the first 16 hex characters of the value's hash. It identifies the value without revealing it.
  • rule ... since: the gbrain version that added or changed the rule (v0.60.31.0 for url_credentials, basic_auth, digitalocean and private keys whose BEGIN or END line is missing; v0.60.502.0 for openrouter, groq, xai, perplexity and replicate). A push that worked before an upgrade and fails after it names the version here.
  • allow this finding: the exact command that appends the fingerprint to the .gbrain-scan-allow file at the repository root. The path is absolute and quoted, so the command works from any directory.
  • retry: the push command to run again, with the same --path, --branch and --allow-unverified-remote you used.

gbrain sources push --json returns the same data in findings[], one object per finding with file, line, pattern, redactedPreview, fingerprint, since, allowlistPath, allowCommand, retryCommand, docs and, when it applies, staleAllowlistEntry. The reason field stays a one-line summary of at most 140 characters (count, first location, pattern), so hook and doctor surfaces show it whole.

Allowlisting a reviewed false positive

First decide whether the value is a real credential. If it is, remove it from the file, rotate it with the provider, and push again; allowlisting a real credential publishes it.

If it is not (a sample value in documentation, a test fixture), run the "allow this finding" command from the refusal, review the change to .gbrain-scan-allow, then run the retry command. The file holds one entry per line: a fingerprint (sha256: and at least 16 hex characters), a path glob (a glob without / matches a file name at any depth; one with / is anchored at the repository root) or a rule entry (below), with # comments. Commit the file so other machines push the same tree.

Prefer a fingerprint over a glob. A glob skips the scan for every file it matches, including credentials added later.

When one rule keeps firing on many harmless values in the same kind of file (for example jwt on the unsubscribe links in saved newsletter HTML), a rule entry allows that rule alone in the files a glob matches:

path:mail/*.html pattern:jwt

Every other rule still runs on those files, so a cloud key pasted into one of them is still refused. Write one rule per line; the glob is the same as a path glob's, and the rule name is the one the refusal prints in brackets. A line that starts with pattern:, or with path: and has a space in it, is read only as a rule entry: if it is malformed (two rules, a missing glob) or names a rule that does not exist, it allows nothing, and the refusal, gbrain git scan and bootstrap verify name the line and what is wrong with it. gbrain git scan also lists each hit a rule entry allowed and the line that allowed it (allowed[] in --json), and gbrain sources push logs them.

A stale allowlist entry for a private key

The fingerprint of a private key whose END line is missing (a cut-off excerpt) covers the key body as well as its BEGIN line. gbrain older than v0.60.31.0 fingerprinted the BEGIN line alone, so an allowlist entry written then does not match and the push is refused. The refusal says so and gives the replacement:

    stale allowlist entry: sha256:<old> matched only this key's BEGIN header before gbrain v0.60.31.0; the fingerprint now covers the key body.
    if the key is a reviewed false positive, replace that line in '/home/you/brain/.gbrain-scan-allow' with: sha256:<new>

Replace the old line only if the key is a reviewed false positive. A cut-off key's fingerprint depends on where the text was cut, so an entry for a truncated key is not stable: if the excerpt changes, the fingerprint changes and the push is refused again. For sample keys in documentation, show a placeholder instead of key material.

Redaction in retrieval output

Every operation that returns retrieved text redacts it before any caller sees it: search, query, evidence delivery, recall, context_pack, delta, entity, synthesize, think, takes, timelines, transcripts and the other retrieval operations. The same pass applies on the CLI, both MCP transports, subagent tools and gbrain call.

A safe way to see it, on a scratch brain with a value made up on the spot:

export GBRAIN_HOME="$(mktemp -d)"
gbrain init --pglite --no-embedding
PW="Gx7$(openssl rand -hex 12)"
gbrain capture --stdin <<EOF
Deploy notes for the scratch redaction check.
clone https://deploy:${PW}@git.example.com/team/repo.git
staging DB_PASSWORD="${PW}#x"
EOF
gbrain search "scratch redaction check" --json | grep chunk_text

Expected (one line, shown wrapped):

"chunk_text": "# Deploy notes for the scratch redaction check.\n\nDeploy notes for the scratch redaction check.\n
clone <REDACTED:url_credentials>git.example.com/team/repo.git\nstaging DB_PASSWORD=\"<REDACTED:high_entropy_assignment>\"",

The host and path stay; only the user and password are replaced. IDs and slugs are never redacted, so do not put secrets in page slugs.

Remembered facts are the one per-caller difference. The fact, context and source fields of recall, context_pack and delta are redacted for remote callers and returned raw to the trusted local CLI on the brain host, so a credential you asked the brain to remember is readable with gbrain recall there. Every MCP caller, including stdio MCP, and a thin client connected over MCP count as remote. Search results, rendered text and entity cards are redacted for every caller.

When an agent sees <REDACTED:pattern>, the brain holds a value of that shape and withheld it. The agent should tell the user that, name the pattern, and point to the brain host for the value. It should not retry other operations to get around it.

What stays raw by design

  • Page reads. get_page, fetch, get_chunks, get_raw_data and get_versions return the stored text unredacted. They are explicit requests for a page and are governed by page visibility, not redaction. Installed skill files (get_skill, get_skill_asset, the skill catalog operations) and admin job operations are raw too.
  • Configured providers. The embedding provider at import, a hosted reranker, and synthesize/think generation still receive stored text unredacted, except private keys, which chunks never contain. Redaction covers what callers receive, not what gbrain sends to a model provider you configured.
  • Your files and database. Redaction never edits stored content. If a real credential reached the brain, rotate it, then follow "If a secret reached the brain".

Git-canonical sources

A source with config.canonical = "git" (strict, set only by conversion; off for every source by default) commits each page file to Git before its database row. Some pages keep no file on purpose: private, alias-private and lineage-private pages (database_only_reason private, alias_private, lineage_private), pages under a storage.db_only directory, derive-phase pages that never recorded a file, paths the checkout's Git ignores (git_ignored), detached pages and origin twins. A write to one of them publishes database-only, with no commit and no Git effect. A page turning private is published as a door commit that removes its file, and its recorded path is cleared in the same publication. Earlier commits keep whatever was pushed before the change; gbrain never rewrites history.

Code What happened What to do
git_home_required The write would store content in the database with no file in Git and is in no declared class (no_file_form), a publication would commit a file for a declared page (declared_target), or a writer with no file form yet wrote to the source (facts_lane). Nothing was written. A fact for an entity with no page, or with no entity, is not refused this way: every fact writer commits it as a row of memory/unattributed instead, or of its folder's <folder>/memory/unattributed when a folder access rule covers the entity. The one exception is an entity with no page under an exact page rule (a rule on the entity's own slug): no holding page carries that rule's readers, so remember refuses with facts_lane and a fix that creates the page (put_page), after which the fact can be remembered again. An owner's gbrain trust release of a held fact for such an entity refuses the same way and the fact stays held; a release onto the page created under that rule then refuses page_not_found (the page is private), so drop the hold and remember the fact on the page. A background fact writer refuses the same way before writing anything: the Google loops extraction still records the loop and logs [loops_extract] fact projection failed … (git_home_required) with the entity's page. Nothing is stored for that fact; once the page exists, the entity's later facts are saved on it. Through remember the frozen error is invalid_params and code is git_home_required. Nor is a fact or take the write gate holds for the owner's review, whatever page it names: it is refused write_held and nothing reaches a page or Git; releasing a held fact commits it to its page's file before its row. On a brain whose managed persistence is disabled that commit cannot happen, so the release refuses with persistence_disabled and the fact stays held; turn managed persistence back on (gbrain sources writer activate), then release again. Ask the user which git home to configure: write the page to a path Git tracks, declare its directory under storage.db_only in gbrain.yml, or mark it visibility: private. gbrain sources git-gap <source> --json shows every page's class. Submit again with a new request ID.
git_private_commit_refused A publication would have committed the file bytes of a private, alias-private or lineage-private page. Nothing was written and HEAD is unchanged. A grouped publication refuses as a whole. The page stays database-only. Write it with put_page, which publishes a private page without a file, or remove visibility: private if it belongs in Git.
git_protocol_required A database trigger refused a row on a strict source because the writing process does not declare the git-canonical protocol: an older gbrain, or gbrain.write_sources set by hand. Nothing was written. Upgrade (gbrain upgrade) or stop every gbrain process that shares the database, then retry with a new request ID.
git_lfs_not_enabled The file falls under a Git LFS rule in .gitattributes, and either storage.git_lfs is off (opt_in_off, the default) or the checkout does not configure the LFS filter or git-lfs does not run (checkout_unconfigured). Nothing was written. Ask the user. To store it with LFS: git lfs install --local in the checkout, then gbrain config set storage.git_lfs true. Otherwise narrow the .gitattributes rule. With the key on and LFS configured, the door commits the LFS pointer and the object goes to the checkout's LFS store; a publication that rolls back can leave an unreferenced object there, which is harmless.

Member access refusals

Per-member read access (members, groups and frontmatter readable_by) lives in the database, so these refusals are the same on a repo-less brain and on a git-backed one.

Code What happened What to do
access_member_invalid A member or group id given to gbrain access, to --member on gbrain auth create, rescope or register-client, or to a local --as <member> is ill-formed (ill_formed) or names no usable member (unknown, disabled, removed, unknown_group), or member add named an existing member (exists). A member's declared email (--email on member add or member set) is not an address (invalid_email), another member already declares it (email_taken), or member link --email found several members declaring it (email_ambiguous; the email is unique, so this means a damaged table). Nothing was read or changed: an unknown --as is refused before the command runs instead of reading as unbound. Check the id with gbrain access member list --all; add the member with gbrain access member add <id> or enable it with gbrain access member enable <id>. Ids are 1-64 characters: lower-case letters, digits, ., _ or -. An email has one @, no spaces and at most 254 characters; clear a taken one with gbrain access member set <id> --email none, and link by member id when an email is ambiguous. member link --email naming an email no member declares is not_found; it never creates a member.
access_member_id_retired gbrain access member add or enable named an id that gbrain access member rm --yes removed. Member ids are never reused, because pages and audit history may still name the removed id. Nothing was created. Choose a new member id. gbrain access member disable is the reversible way to pause a member.
access_member_disabled The access token or OAuth client is bound to a member who is disabled, removed or missing, so it was refused at verification (HTTP 401, invalid_token with this code in the description). A credential bound to a member reads as that member, so it is refused rather than silently treated as unbound. Ask the brain operator to run gbrain access member enable <id>, or to rebind the credential with gbrain auth rescope --token <name> --member <id> (--member none unbinds it; an unbound credential sees no page that names readers). On the host, gbrain auth list shows such a token as refused (member_status in --json), and a thin client prints this code instead of "credentials may have been revoked". Disabling a member lists the pages it leaves readable by no member, and gbrain access who-can-read <slug> names the gbrain repair visibility --slug <slug> --readers <member>,<owner> write that gives one back.
access_identity_unavailable The member a credential (access token, OAuth client or stdio binding) is bound to could not be looked up: the database failed the statement, or timed out or dropped the connection while the request was submitted. The request was refused and nothing was read or written. Reading the credential as unbound instead would open every unlabelled page to a labelled-only member. Retry the same request in a few seconds; a write keeps the same request_id. whoami shows the member the connection reads as once the lookup works again. If it keeps failing, the brain operator runs gbrain doctor --json on the brain host.
access_rule_invalid gbrain access rule add was given a rule whose prefix is not a literal lower-case slug folder ending in / (or holds .. or *), whose readers are not member ids or group:<id>, or whose prefix another rule already covers; nothing was written. Prefixes match slugs literally, so a pattern or typo would restrict the wrong pages. Write the prefix as a folder such as partners/alice-example/ and the readers as alice-example,group:team-a; to change who reads a folder that already has a rule, pass that rule's --id.
access_policy_invalid A source's committed .gbrain/access.yml (or a file given to gbrain access rule import) does not validate. The last applied rules stay in force and every prefix the file names reads as nobody for remote callers (the whole source when the file does not parse), so a typo never opens a folder. In a partial clone (git clone --filter), a policy file or an earlier version of it that the clone never fetched makes the whole source read as nobody the same way, because sync fetches nothing. gbrain access rule list --source <id> shows each problem with its line. Fix the file, commit it with gbrain git commit-push, and run gbrain sync --source <id> --no-pull. In a partial clone, run the git cat-file -p or git log -p the problem names in the checkout, which fetches what is missing, then sync the same way.
access_policy_pending A narrowing change to a source's folder rules is still being stamped onto its pages, so pages under the folders it touches read as nobody for remote callers until it finishes (other folders keep the last applied rules). Remote reads carry this as a notice: an empty answer there is not proof of no notes. On a git-canonical source, a remember for an entity with no page whose access rules this database role cannot read refuses with it (frozen error unavailable, next: wait), because gbrain cannot tell which holding page has the entity's readers; nothing was written. A passing database error on that read while the write is being prepared (a cancelled statement, a lost connection, a lock conflict) is not this refusal: the write queue prepares the write again. An owner's gbrain trust release of a held fact for such an entity refuses the same way and the fact stays held. A background fact writer (the Google loops extraction) refuses the same way; the loops job records the loop and logs the code with the entity's page. Wait and retry. If it stays pending the apply was interrupted: on the brain host run gbrain access resume --source <id> (database store) or gbrain sync --source <id> --no-pull (git store); gbrain access rule status --source <id> shows the pending folders.

Shared-agent refusals

A shared agent's harness names the audience a request serves in the X-Gbrain-On-Behalf-Of header or request-level _meta.on_behalf_of. These refusals come before any read, and none reveals page content. may_act_for and members live in the database, so they are the same on a repo-less brain.

Code What happened What to do
on_behalf_of_invalid_audience The audience is empty, holds more than 50 entries, holds an entry that is not a member id, group:<id> or guest, or the header and _meta.on_behalf_of name different audiences (_meta.on_behalf_of must be a list of strings). Nothing was read. Fix the harness code that sets it: 1-50 entries, the same in both channels when both are sent. Name a group:<id> for a channel larger than 50 people.
on_behalf_of_unknown_member The audience names a member who is disabled, removed or was never added, or a group that does not exist. It is refused rather than read as a guest. Nothing was read. Name enabled members and existing groups only (gbrain access member list --all, gbrain access group list); a person who is not a member joins the audience as guest.
on_behalf_of_not_permitted The credential's may_act_for (for a stdio server, config mcp.stdio_may_act_for) does not list every audience entry. The message names the credential and the entries it may not act for. Nothing was read. The brain operator decides: fix carries gbrain auth rescope --token <name> --may-act-for <list> (or --client <id>, or gbrain config set mcp.stdio_may_act_for <list>) with the full list to approve. The agent never runs it; until then, call without the audience.
on_behalf_of_in_arguments A tool call carried on_behalf_of in its arguments (top level or an arguments-level _meta), where conversation text could set it. Nothing was read. Remove it from the arguments. Harness code sends the audience as the header or request-level _meta.on_behalf_of; a stdio client that cannot set request-level _meta uses a credential bound to one member or config mcp.stdio_member.

Guest source refusals

A guest source (gbrain guests init, guest notes) holds notes saved for people outside the brain. Its pages are written only by the credentials on its writer list, once each, as new pages; everything else is refused before anything is written. The rules live in the database, so they are the same on a repo-less brain.

Code What happened What to do
source_writer_restricted A write to a guest source came from a credential that is not on the source's writer list: a remote token or client that was never listed, the local CLI (gbrain put, gbrain import, remember, add_link), an enforced member, or a listed writer that was removed between admission and publication (the receipt ends failed with this code). Only the brain owner on the brain host may delete or restore a guest page. Nothing was written. Do not retry. Write the content to another source. Who may write a guest source is the brain owner's decision; an agent never changes the writer list.
guest_page_immutable A listed writer tried something other than saving a new page: a write with force or expected_revision, edit_page, append_page, add_timeline_entry, add_link, remember, put_pages, an upload, or a put_page over a deleted guest page. The database refuses facts, takes and timeline rows in a guest source with the same code. A plain put_page to a slug that already exists is refused revision_required. Nothing was written. Save the note again under a new slug. To change a guest note, the brain owner promotes it to an owner page and edits that.
guest_page_promoted A remote delete_page of a guest note the brain owner kept as an owner page (gbrain guests promote); checked when the delete is submitted and again when it publishes. The owner's own delete from the local CLI still works. Nothing was deleted. Do not retry. Treat the note as kept: it reads guest.promoted: true. Only the brain owner removes it, on the brain host.
permission_denied (another writer's guest note) A listed writer's remote delete_page of a guest note whose guest mark names a different writer: a writer deletes only the notes it saved. Checked when the delete is submitted and again when it publishes. The owner's own delete from the local CLI still works. Nothing was deleted. Do not retry. Delete only the notes this credential saved; the brain owner deletes any guest note on the brain host (gbrain delete).
guest_attribution_missing A listed writer's put_page carried no guest attribution, or a malformed one. Attribution is the X-Gbrain-Guest header (sender_label=<URL-encoded label>&group=<group-slug>) or request-level _meta.guest ({"sender_label": "...", "group": "..."}). A label is 1 to 64 characters with no control, format or line-separator characters and none of ·, [, ], <, > or "; a group slug is 1 to 64 of a-z, 0-9 and -. Sending both with different values is refused too. Nothing was written. Fix the harness code that sets it, then save the note with a new request_id. Attribution sent with a write to any other source is ignored.
guest_frontmatter_refused A guest page's frontmatter held a key outside type, title, readable_by, guest_group, guest_sender and saved_at (for example visibility, trust_tier, tags or always_load), or its guest_sender or guest_group differs from the attribution. Nothing was written. Send only the allowed keys, with guest_sender and guest_group equal to the attribution's sender_label and group.
guest_readers_invalid A guest page's readable_by is not exactly the brain owner plus the one member or group the call speaks for (X-Gbrain-On-Behalf-Of), the call speaks for several principals or for guest, or the brain has no owner set. A missing readable_by under an audience is refused readable_by_invalid first. Nothing was written. Speak for one member or group and set readable_by to the owner and that principal, for example [alice-example, group:team-a]. The owner is set on the brain host with gbrain access owner set.
guest_promotion_owner_only promote_guest_note came from someone other than the brain owner: a broker, a member's credential, the owner's credential speaking for a group or another member, an enforced member, a subagent or an --as preview. Only the trusted local CLI and a credential or stdio server bound to the owner, speaking for no one else, promote. Nothing was read or written. Do not retry. Ask the brain owner; if they want to keep the note, they run gbrain guests promote <slug> on the brain host.
guest_mark_immutable Something tried to change a guest mark (who a guest page was saved for, from which group, when and by which writer). A mark is never changed; it leaves only with its page. Nothing was written. Do not retry.
guest_source_database_only A guest source was given a local path or repository, or a source that has one was made a guest source. A guest source is database-only. Nothing was written. Use a new source id for the guest source (gbrain guests init --source <id>).

Unscoped reads on a brain that serves several people

A brain serves several people when two or more members are enabled, or when config access.serves is several (gbrain access serves says which and why; an explicit one wins over the member count). On such a brain every remote read must say whom it reads for: a credential bound to a member (--member, the owner included), a shared agent naming its audience per call (--may-act-for plus X-Gbrain-On-Behalf-Of), or an attested person. A brain for one person, with any number of sources, sees no change. Writes are not affected. Everything is database state, so a repo-less or keyless brain behaves the same.

A connection that existed when the brain started serving several people (config access.serves_since, or the upgrade that added it, whichever is later) keeps reading for 14 days; each answer then carries _meta.access.requester_scope with state: "grace", refuses_at, the connection and fix. A local stdio server and a credential with no recorded creation time count as existing. Hosted brains set access.requester_scope_enforce false until their control plane binds each connection to a member: the notice then reads state: "not_enforced" and nothing is refused.

Code What happened What to do
requester_scope_required A remote read came from a connection bound to nobody. reason says which: grace_ended (the connection is older than the brain's several-people date and its 14 days ran out), created_after (it was created after that date, so it had to be scoped at creation) or since_unknown (the date could not be read; fail closed). The message names the connection and the operation. Nothing was read; the code is also in structuredContent.error.code and the audit trail (access-audience). Read-only identity and health calls (whoami, get_brain_identity, get_status_snapshot, search_modes, get_health, and a non-admin credential's own get_job / wait_job) still answer. The brain operator runs fix on the brain host: gbrain auth rescope --token <name> --member <id> (or --client <id>; preview with gbrain access check --token <name>), or for a stdio server, when only one person uses that harness, `gbrain setup claude-code
requester_scope_unknown A remote read came from a connection bound to nobody, and gbrain could not tell whether the brain serves one person or several: its config read failed (a statement timeout, a lock wait or a dropped pooled connection) and so did one re-read of the serves keys. Nothing was read. The message says the brain's settings could not be read and that this is not an access decision; it does not claim the brain serves several people, because that is what could not be read. This applies on a brain pinned access.serves one too, since the pin is one of the settings that failed to read. A connection bound to a member is never refused this way. Retry the same call after retry_after_ms (fix.next is wait). If it keeps failing, the brain host's operator checks the database with gbrain doctor --json; fix.verify (gbrain access serves --json, read-only) confirms the settings read again.
credential_scope_required gbrain auth create or gbrain auth register-client was asked for a credential bound to no member on a brain that serves several people. Nothing was created. Pass --member <id> (gbrain access member list), or --may-act-for <members> for a shared agent. --reads-unscoped --yes creates one that reads unscoped on purpose.

Attested-actor refusals

A trusted system (QM) names the person a call serves in the x-qm-actor header, as an opaque canonical id that the brain operator links to a member (gbrain access member link <member> --qm <id>). The credential must hold the attest right (gbrain auth rescope --client <id> --attest-actor qm). These refusals come before any read or write, none reveals page content, and each carries its code in structuredContent.error.code as well as the JSON text block. Links and the right live in the database, so they are the same on a repo-less brain.

Code What happened What to do
actor_not_attested The call named a person in a way gbrain does not honour. reason says which: no_attest_right (the credential holds no attest right, or the token of an attest client was issued before the upgrade or by another grant: the message then says to take a new client-credentials token), op_not_attested (the operation is not in the credential's attested operations, or is not attestable yet: list_write_conflicts, capture, extract_facts, `takes_add update
permission_denied reason source_not_attested / scope_page_not_shared, invalid_params reason source_is_member_source A scope memory_write (source_id, contract v2) named a source that is not in the credential's --attest-sources or not a marked scope source (also when a queued write publishes after the source was dropped), or its own write source; or the scope's memory/scope page names readers, is private or sits under a folder rule. Nothing was written. The operator lists the source with gbrain auth rescope --client <id> --attest-sources <list>, or removes readable_by / visibility: private / the folder rule from memory/scope. For the person's own page, leave source_id out. See shared scopes.
actor_unlinked The id is not linked to an enabled member: never linked, unlinked, or the member is disabled or removed. Ids compare exactly, with no case folding. Nothing was read or written. A queued write or agent job made for the person is refused the same way when its link is gone or now names another member. memory_recall answers it as an empty success instead (structuredContent: {facts: [], truncated: false, code: "actor_unlinked"}), so a person not yet linked reads nothing. The brain operator links it: gbrain access member link <member> --qm <id> (or gbrain access member enable <member>).
proposals_pending_limit A memory_propose found too many proposals already awaiting the owner: reason is actor (this person, proposals.max_pending_per_actor, default 10) or credential (this QM credential, proposals.max_pending_per_credential, default 50). An overdue proposal frees its slot first. Nothing was saved. Wait for the owner to decide or for a proposal to expire, or withdraw one with cancel_write_request, then send it again with the same idempotency_key. The brain operator sets the caps.

Storage manifest refusals

The storage shelf (source storage) holds one validated card per item an agent archived to object storage. Only the storage verbs write it (gbrain storage-register, gbrain storage-update, and gbrain storage adopt and gbrain storage import, which register through the same path), from the trusted local CLI. Guide: storage manifest. An adopt or import apply whose plan changed since its preview refuses preview_changed; storage_record_invalid and storage_record_secret there name the interim page or JSONL line instead of a field you sent.

Code What happened What to do
storage_source_managed put_page, remember or another page writer targeted the shelf. Register with gbrain storage-register, change with gbrain storage-update.
storage_record_invalid A card field is missing or malformed, names a command (command, script, exec and similar), or is one gbrain sets itself (registered_by, origin). On adopt, reason access_unpreservable means an interim page's readable_by and the folder rules over it share no reader, and access_pending that a rule over it is still being applied, so no card could carry the same restriction; on import, labels means a line's labels holds something other than access labels; remote_written means a remote (MCP) client last wrote the interim page, so adopt never registers it (check it and use gbrain storage-register); truncated means the interim page is longer than the 64 KiB adopt reads and its ## Record block is cut off or past that point. storage_get refuses it too for a stored card that breaks these rules, such as a hand-edited card file. Fix the field the message names. Restore runs through restore.skill and restore.args. For access_pending, finish the rule change (gbrain access status) and preview again; for access_unpreservable, give the page readers its folder rules also list; for truncated, move the ## Record section to the top of the page. For a stored card, gbrain doctor --only storage_manifest lists the invalid cards, and the refusal carries the card's revision for gbrain storage-update <id> --expected-revision <rev> --patch '<json>'.
storage_record_secret A field looks like a secret or has a credential shape: an environment assignment, a credential-named variable, a URL password, a signed-URL parameter, or a value under a credential-named key such as password or token_value. The value is not echoed. Remove it; the restore skill reads credentials from its own environment. A key that holds no credential can be renamed to end in _id, _ref, _name, _path, _file, _env, _var or _variable.
storage_card_exists A card with that id is already registered. Update it with the revision storage_get returns, or use another id.
storage_revision_conflict The card changed since its revision was read; detail holds the current revision. Read it again, apply the change, update once.
storage_manifest_missing No shelf yet on a brain with a Git checkout, or the storage source ID belongs to another source. Preview gbrain storage init --dir <path> --dry-run and apply it after the user agrees (it needs managed persistence).
storage_adopt_field_refused gbrain storage adopt --apply found interim records with fields a card refuses (a command, an unknown field, a stamped field) that it was not told to drop. Show the user the fields the preview lists; with their agreement, run the apply the refusal names (one --drop-field per field). The original pages keep them until finalize.
storage_adopt_unverified gbrain storage adopt --finalize found an adopted original whose card is missing or differs from its record. Nothing was deleted. Compare the original with its card (gbrain storage-get), fix one of them, and preview finalize again.

Related