# gbrain-sync error lookup Every error message `gstack-brain-*` can print, with problem, cause, and fix. Search this file by the prefix after `BRAIN_SYNC:` or by the binary name in the command output. --- ## `BRAIN_SYNC: brain repo detected: ` **Problem.** You're on a machine that has `~/.gstack-artifacts-remote.txt` (or the legacy `~/.gstack-brain-remote.txt`, copied from another machine) but no local git repo at `~/.gstack/.git`. **Cause.** You've set up GBrain sync elsewhere and your gstack hasn't been restored on this machine yet. **Fix.** ```bash gstack-brain-restore ``` This pulls the repo into `~/.gstack/` and re-registers merge drivers. If you don't want to restore here, dismiss the hint with: ```bash gstack-config set artifacts_sync_mode_prompted true ``` --- ## `BRAIN_SYNC: blocked: :` **Problem.** Sync stopped because the secret scanner detected credential-shaped content in a staged file. The queue is preserved; nothing was pushed. **Cause.** One of the pre-commit secret patterns matched the file contents — likely an AWS key, GitHub token, OpenAI key, PEM block, JWT, or bearer token embedded in JSON. **Fix (three options).** 1. **If it's a real secret**: edit the offending file to remove the secret, then re-run any skill to retry sync. 2. **If the pattern is a false positive** (e.g., your learning contains a GitHub token pattern in an example string that you *want* to publish): ```bash gstack-brain-sync --skip-file ``` This permanently excludes the path from future syncs. 3. **If you want to abandon this sync batch entirely** (start fresh): ```bash gstack-brain-sync --drop-queue --yes ``` This clears the queue without committing. Future writes will re-populate it normally. --- ## `BRAIN_SYNC: push failed: auth.` **Problem.** Git push was rejected because your auth with the remote expired or is missing. **Cause.** The remote is unreachable with current credentials. **Fix.** Refresh auth based on your remote: - **GitHub**: `gh auth status` (then `gh auth refresh` if needed) - **GitLab**: `glab auth status` - **Other**: `git remote -v` + check SSH keys or credential helper After fixing auth, run any skill to retry sync automatically. --- ## `BRAIN_SYNC: push failed: ` **Problem.** Push failed for a reason other than auth. The first line of git's error appears after the colon. **Cause.** Could be network issue, rejected push (remote ahead), server 500, or repo access revoked. **Fix.** Look at `~/.gstack/.brain-sync-status.json` for more detail, or run: ```bash cd ~/.gstack && git status && git push origin HEAD ``` to see git's full error. The queue is cleared after any push attempt, but your local commit still exists — the next skill run will retry the push. --- ## `gstack: brain-sync push NOT sent — the egress receipt could not be written` **Problem.** The push was refused before anything left your machine. Every brain-sync push writes a tamper-evident receipt to the egress ledger (`~/.gstack/security/egress.jsonl`) before sending, fail-closed. The receipt could not be written, so nothing was sent, no local commit was made, and the queue is preserved — the next run retries the whole drain. `gstack-brain-sync --status` shows `EGRESS_RECEIPT_FAILED` as the failure detail. **Cause.** `~/.gstack/security/` is not writable (the receipt writer creates it when missing, so absence alone is not the cause), the disk is full, or `GSTACK_HOME` points at a read-only location. **Fix.** ```bash mkdir -p ~/.gstack/security && chmod -R u+w ~/.gstack/security ``` Then run any skill (or `gstack-brain-sync --once`) to retry. Inspect the ledger with `gstack-egress list`; verify its hash chain with `gstack-egress verify`. --- ## `gstack-artifacts-init: ~/.gstack/ is already a git repo pointing at: ` **Problem.** You tried to init with a remote URL that doesn't match the existing one. The command refuses to overwrite. **Cause.** You already ran `gstack-artifacts-init` with a different remote. **Fix.** Either: - Use the existing remote: run `gstack-artifacts-init` without `--remote`, or with the matching URL. - Switch remotes: `git -C ~/.gstack remote set-url origin ` (the command's own suggestion), or `gstack-brain-uninstall` first, then re-init with the new URL. Neither deletes your data. --- ## `Remote not reachable via SSH: ` **Problem.** Init couldn't reach the git remote to verify connectivity. **Cause.** Wrong URL, missing auth, network issue. **Fix.** Test manually: ```bash git ls-remote ``` If that fails, check: - URL spelling - GitHub: `gh auth status` - GitLab: `glab auth status` - Private network / VPN / DNS --- ## `Failed to create or find ''. Try --remote .` **Problem.** Auto-repo-creation via `gh repo create` failed and the repo isn't discoverable via `gh repo view` either. **Cause.** `gh` is unauthenticated, a repo with that name already exists owned by someone else, or your GitHub account hit a quota. **Fix.** ```bash gh auth status ``` If unauth'd, run `gh auth login`. If the repo name collides, pass a different name: ```bash gstack-artifacts-init --remote git@github.com:YOURUSER/custom-name.git ``` --- ## `gstack-brain-restore: ~/.gstack/.git already points at ` **Problem.** You tried to restore from a URL that doesn't match the existing git config. **Cause.** Stale `.git` from a previous init with a different remote. **Fix.** `gstack-brain-uninstall`, then re-run `gstack-brain-restore `. --- ## `gstack-brain-restore: ~/.gstack/ has existing allowlisted files that would be clobbered` **Problem.** You're trying to restore, but `~/.gstack/` already contains learnings or plans that would be overwritten. **Cause.** Either (a) this machine has accumulated state from a pre-sync gstack session, or (b) a previous failed restore left partial state. **Fix (three options).** 1. **If this machine's state should become the new truth**: run `gstack-artifacts-init` instead of restore — this creates a brand-new brain repo from this machine's state. 2. **If you want to adopt the remote and discard this machine's state**: back up `~/.gstack/projects/` first, then remove the offending files and re-run restore. 3. **If you want to merge**: there's no automatic merge for this. Manually copy learnings from `~/.gstack/` into your running gstack on a machine with sync already on, then restore here. --- ## `gstack-brain-restore: does not look like a gstack-brain repo` **Problem.** The clone succeeded but the repo is missing `.brain-allowlist` and `.gitattributes`. **Cause.** You pointed restore at a random git repo, or someone deleted the canonical config files from the brain repo. **Fix.** Verify the URL. If it's correct, run `gstack-artifacts-init --remote ` to re-seed the canonical config. --- ## `database host unreachable ( ); your gbrain config is unchanged. Fix: check network or VPN, then re-run /sync-gbrain.` **Problem.** `/sync-gbrain` skipped the code, memory and dream stages, or `/setup-gbrain` reported `gbrain_local_status: db-unreachable`. **Cause.** gbrain could not reach the database named in `~/.gbrain/config.json` because of a network error (`ENOTFOUND` / `EAI_AGAIN` in an offline sandbox, a VPN that is down, a refused or timed-out connection). Nothing is known to be wrong with the config, so gstack leaves it alone and keeps brain-aware skill blocks rendered, the same way it treats a slow `timeout`. **Fix.** Restore network access (or the VPN), then: ```bash /sync-gbrain ``` Do not move `~/.gbrain/config.json` aside; that remediation is only for `broken-db` / `broken-config`. --- ## `[memory-ingest] ... dot-leading slug` (pages under `.claude`-style project slugs never landed) **Problem.** Before this release, ingest refused every batch that held a page from a project whose slug starts with a dot (for example `.claude`), with `gbrain import accounted for N-1 of N staged page(s) ... Refusing to advance state`. **Cause.** gbrain's import walker skips every path segment that starts with a dot, so the staged page was never collected. **Fix.** Nothing to do after upgrading: such slugs now stage as `dot-claude`, and state recorded under the old name maps to the new one. Run `/sync-gbrain` once to import the pages that were stuck. --- ## `[memory-ingest] FAILED : (left un-stamped; retried next run)` **Problem.** gbrain refused one staged page during `/sync-gbrain`'s memory stage (for example invalid frontmatter or an oversize page). **Cause.** `gbrain import` named the page as a per-file failure (in its `--json` `failures` list or a `Skipped :` line). Before this release, such pages were marked ingested and never retried. **Fix.** Nothing is lost: the page is not marked ingested and is retried on every run. If the same page keeps failing, read the error, fix the source file it came from, then run `/sync-gbrain`. --- ## `[memory-ingest] re-queued : not found in gbrain source after import (retried next run)` **Problem.** gbrain said a page was imported (or unchanged), but the landing check could not find it in the source it was imported into, or found different content. **Cause.** Usually a managed import that was accepted but is still publishing (`Pending:` in gbrain's output), or a page gbrain skipped without naming it. **Fix.** Nothing to do; the next `/sync-gbrain` imports it again. If it repeats on every run, upgrade gbrain (`gstack-gbrain-install`). --- ## `[memory-ingest] ERR: gbrain reported N failure(s) it did not attribute to a staged page ... Refusing to advance state.` **Problem.** The memory stage failed and marked nothing ingested. **Cause.** gbrain counted failures it did not name (it stops printing them after five of the same kind), so gstack cannot tell which pages landed. **Fix.** Re-run `/sync-gbrain`. After three refused runs the batch is split in halves automatically to find the page gbrain cannot import; that page is quarantined (next entry) and the rest import. --- ## `[memory-ingest] quarantined (): gbrain refuses every batch that contains it (...)` **Problem.** One page kept making gbrain refuse the whole batch. **Cause.** After three refused batches, gstack imported the batch in halves until it isolated the page. Every other page was imported. **Fix.** The page is retried automatically when its source file changes. To retry now, fix or remove the source file named in the message, then run `/sync-gbrain`. --- ## `[memory-ingest] reconcile: checked N, present M, re-queued K, not yet checked L (run again to continue)` **Problem.** Not an error. This is the one-time catch-up after upgrading: gstack re-checks transcripts it had marked ingested and re-queues the ones missing from the brain, so transcripts lost by older versions import again. **Cause.** Older versions could mark a page ingested that gbrain had skipped. The upgrade records that a reconcile is pending; each ingest run then checks a bounded batch (200 entries) until done. **Fix.** Nothing to do; each `/sync-gbrain` continues where the last one stopped. To run it now or check progress: ```bash gstack-memory-ingest --reconcile --dry-run # report only gstack-memory-ingest --reconcile # re-check the next 200 (--limit N) ``` "not yet checked" counts pages whose lookup failed (gbrain busy or unreachable); they are never treated as missing. "unrecoverable" counts pages missing from the brain whose transcript file no longer exists. The state file is backed up to `~/.gstack/.transcript-ingest-state.json.pre-reconcile.bak` before each pass. --- ## `[memory-ingest] reconcile: not run (...)` **Problem.** A reconcile pass was requested but could not run. **Cause.** gbrain is not installed or lacks `import`, or the brain is a remote-HTTP brain (its pages are staged for the brain admin's pull, so there is nothing to check locally). **Fix.** For a missing gbrain, run `/setup-gbrain`, then `gstack-memory-ingest --reconcile`. For a remote-HTTP brain, nothing to do. --- ## `[memory-ingest] ERR: another memory ingest (pid ) is writing ; not run.` **Problem.** The memory stage did nothing this run. **Cause.** Another ingest, reconcile or `--request-reconcile` holds the state lock (`~/.gstack/.transcript-ingest-state.json.lock`). A lock left by a process that no longer exists is taken over automatically. **Fix.** Wait for the other run to finish, then run `/sync-gbrain` again. --- ## `[memory-ingest] ERR: could not save ingest state : .` **Problem.** The memory stage failed after importing. **Cause.** The state file could not be written (disk full, permissions, or a directory in its place). The run fails instead of pretending it recorded progress; pages it imported are re-checked next run, which is cheap because gbrain skips unchanged content. **Fix.** Free disk space or fix permissions on `~/.gstack/`, then run `/sync-gbrain`. --- ## `[memory-ingest] kept N unattributed transcript(s) on this machine: the brain is remote (Postgres or HTTP), ...` **Problem.** `--include-unattributed` transcripts (sessions with no git remote) were not imported. **Cause.** Transcripts that cannot be attributed to a repository go only to the machine-local, never-federated source `gstack-transcripts-unattributed`. Your brain is remote (a Postgres or Supabase `database_url`, or a remote-HTTP MCP brain), so sending them would take them off this machine. They are not marked ingested and are not written to the publishable `~/.gstack/transcripts/` staging either. **Fix.** Nothing to do if that is what you want. To include such a session, run it from a git repository with an `origin` remote so it is attributed. --- ## `[memory-ingest] kept N transcript page(s) for on this machine: could not register gbrain source (...)` **Problem.** Transcripts from one repository were not imported. **Cause.** gstack imports each repository's transcripts into that repository's own gbrain source (`gstack-transcripts-...`, machine-local and not federated) and registers it before the first import. The installed gbrain refused `gbrain sources add`, so the pages stay local and unstamped. **Fix.** ```bash gstack-gbrain-install # upgrade gbrain /sync-gbrain # the pages import on the next run ``` --- ## Nothing is syncing but I expect it to **Not an error, but a common gotcha.** Check in order: 1. `gstack-brain-sync --status` — is mode `off`? 2. `~/.gstack/.git` exists? 3. `gstack-config get artifacts_sync_mode` — should be `full` or `artifacts-only`. 4. The file you expect to sync — is it in the allowlist? `cat ~/.gstack/.brain-allowlist` 5. Privacy class filter — if mode is `artifacts-only`, behavioral files (timelines, developer-profile) are intentionally skipped. If all those look right, run: ```bash gstack-brain-sync --discover-new gstack-brain-sync --once ``` to force a drain.