mirror of
https://github.com/garrytan/gstack.git
synced 2026-10-31 22:14:25 +01:00
garrytanandSinabina
d02c8effb7
`gbrain import` ran without --source-id, so transcripts from every project
landed in the shared (often federated) default source.
- Each transcript partition imports with --source-id into its originating
repository's own source (gstack-transcripts-<repo>, built with
constrainSourceId, now exported from lib/gbrain-sources.ts). The source
is registered machine-local and --no-federated before its first import,
and the registration is cached in state. Partitions import one after
another (PGLite is a single writer); a failing source no longer blocks
the others, except a timeout, whose checkpoint must survive.
- If gbrain cannot register the source, that partition stays local and
unstamped, and the run says why (even under --quiet).
- --include-unattributed sends repo-less transcripts only to the
machine-local gstack-transcripts-unattributed source, keeps them on the
machine when the brain is remote (Postgres, Supabase or remote-HTTP),
and never writes them to the publishable ~/.gstack/transcripts staging.
- A page's recorded source is sticky: pages stamped before this release
("default") keep importing there, so no source gains a duplicate.
- The staging dir name carries -src-<id> so a resumed import keeps its
source.
Test fakes that recorded only the last import now record every import of
one run, and answer `gbrain sources`; remote-http scan tests use an
attributed transcript, since unattributed ones no longer stage there.
Co-authored-by: Sinabina <sinabina@Sinabinas-MacBook-Pro-4.local>
429 lines
15 KiB
Markdown
429 lines
15 KiB
Markdown
# 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: <url>`
|
|
|
|
**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: <pattern-family>:<snippet>`
|
|
|
|
**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 <path>
|
|
```
|
|
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: <first-line-of-error>`
|
|
|
|
**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: <url>`
|
|
|
|
**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 <url>` (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: <url>`
|
|
|
|
**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 <url>
|
|
```
|
|
If that fails, check:
|
|
- URL spelling
|
|
- GitHub: `gh auth status`
|
|
- GitLab: `glab auth status`
|
|
- Private network / VPN / DNS
|
|
|
|
---
|
|
|
|
## `Failed to create or find '<name>'. Try --remote <url>.`
|
|
|
|
**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 <url>`
|
|
|
|
**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 <url>`.
|
|
|
|
---
|
|
|
|
## `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: <url> 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
|
|
<url>` to re-seed the canonical config.
|
|
|
|
---
|
|
|
|
## `database host unreachable (<code> <host>); 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 <path>: <error> (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 <path>:` 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 <slug>: not found in gbrain source <id> 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 <slug> (<source path>): 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 <N>) is writing <state file>; 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 <path>: <error>.`
|
|
|
|
**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 <repo> on this machine: could not register gbrain source <id> (...)`
|
|
|
|
**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.
|