Garry's Opinionated OpenClaw/Hermes Agent Brain
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(factsortakes),section(bodyortimeline),rows(row numbers),columns(column names) andline(the first bad line, counted within the section).- The reason's
tier, the repair that clears it (deterministic,resolver,llmormanual), andauto_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'sreason,tierandat,next_attempt_after(when the maintenance run tries it again; null when it will not), andgateandrowswhen a proposed repair was rejected. fix, the next command (a single held file's preview,gbrain repair fences --source <source> --only <path>), anddocs, 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."
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 answersisError: falsewithstatus: "pending",request_id,receipt(statequeued),deferred: { refresh_id }andnext(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
conflictwithrevision_conflictnaming 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 itpermission_denied. - A write whose refresh is still unfinished after
persistence.refresh_barrier_max_wait_ms(default 15 minutes) endsfailedwithrefresh_barrier_expired, nothing applied. Check the refresh withgbrain sources writer status --source <source> --json, then submit again with a new request ID. - A refresh in
recovery_requiredholds 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,rememberoradd_timeline_entrywhose page file holds a committed change managed sync has not imported yet (pending_import) also waits instead of being refused: the receipt stays pending withdeferred: { pending_import: true }, and once the import lands the write is prepared again against the imported page. Arememberoradd_timeline_entryapplies on top; aput_pagewithexpected_revisionendsrevision_conflictwhen the import moved the page; a blind (force)put_pageor acapturelands 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, endsfailedwithpending_import_expired, nothing applied: checkgbrain sync status --source <source> --json, then read the page again and submit with a new request ID. Arememberends as thepending_importrefusal 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; otherwisegbrain 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 refreshrun on the owner host (the same run,--resumeor--abandon, or the next tick, even one refusedrefresh_diverged) ends by running the managed--no-pullsync 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 waitingrememberoradd_timeline_entryis the exception: it still applies on top. - Still refused as before: batches (
put_pages,rememberwithitems), 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 --jsonshowsdeferred: { 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-downgradeto exit 0. It exits 3 withdowngrade_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); pollinggbrain write-requestonly 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:
- Write the file, commit, sync (the classic write path). Write or edit
<checkout>/<slug>.md, check generated frontmatter withgbrain frontmatter validate --stdin --path <slug>.md, commit it withgbrain git commit-push --path <checkout> -m <msg> -- <slug>.md, then rungbrain sync --source <id>. Sync imports commits;--working-treeimports uncommitted edits for one run. Delete the file, commit the deletion the same way, sync. Tags and timeline entries are frontmatter and## Timelinelines in the same file. - 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. - 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 syncof 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:
- Bind the source on the host that holds the checkout. Run
gbrain sources writer status <source> --jsonand noteadmin_state, thengbrain 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. - Allow database-only writes with
gbrain config set persistence.unbound_write database_only(the default isrefuse; 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, thetakes_*writes, and aremember(or loop-close retirement) whose fact is fenced into that page's database body. Its result sayswrite_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, rungbrain 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:
- Confirm with the user that the recorded brain is retired: it was moved into
this database, or it was deleted on purpose.
gbrain doctor --jsonon the old brain's home, if it still exists, shows itsbrain_id. - 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|acceptinstead. - 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,digitaloceanand private keys whoseBEGINorENDline is missing; v0.60.502.0 foropenrouter,groq,xai,perplexityandreplicate). 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-allowfile 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,--branchand--allow-unverified-remoteyou 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_dataandget_versionsreturn 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/thinkgeneration 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.
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.
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.
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.
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.
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
- Concurrent writes and durable receipts — receipt states, retries, capacity limits
- Repair residual damage —
gbrain repairfor history, visibility and safe-chunk damage - Multi-source brains — sources, slug-root mode and write-through
- Topologies — the writer administration procedure behind self-transfer