Skip to main content
When gc start fails, the last line is a FATAL: marker. The line below it is a URL that links here. Find your symptom in the lookup below, then expand its section for the cause and resolution.
This page covers the seven failure modes encountered in the 2026-04-26 selfhost UX bug haul (umbrella PRD ga-r8hs). For installation issues (gc not on PATH, missing prerequisites, version mismatches), see Troubleshooting. For Dolt store recovery, see Dolt bloat recovery.

​
What a failed gc start looks like

Failed gc start showing the FATAL prefix, warning de-duplication, and walkthrough URL — left panel is the TTY render with bold-red FATAL, right panel is the non-TTY render with plain ASCII FATAL prefix. The FATAL: prefix is the stable marker — bold red on a TTY, plain gc-fatal: ASCII when piped or redirected. The same line ends with see: <URL> pointing to the matching section below.

​
Quick lookup

If your symptom does not match any of the above, run gc doctor --verbose and consult the installation troubleshooting page. If still stuck, file an issue (link at the bottom of this page).

​
  1. bd op_init timeout

Symptom
Or gc start hangs and the supervisor cycles through starting_bead_store retries with no actionable error. Cause bd >= 1.0.3 triggers a config schema auto-migration on every bd config set call. Older versions of the gc-beads-bd shim issued two bd config set invocations during op_init, taking 18s and ~50s respectively — each SIGKILL’d by the 30s op_init provider timeout. The supervisor never reached ready state. Fixed in ga-5mym.1 by replacing the slow path with a direct .beads/config.yaml write (idempotent, < 5s wall clock). Resolution Upgrade gc to 1.1.0 or later. Verify:
If gc start still hangs after upgrading, check that your gc binary on disk matches the running supervisor — see Pack schema mismatch for the drift-detection flow.

​
  1. Pack schema mismatch

Symptom
Typically appears after running go install ./cmd/gc while the supervisor is still running. Cause The on-disk gc binary was rebuilt and now understands pack schema 2. The running gascity-supervisor (a long-lived systemd user service) keeps executing the previous binary’s image and the cached pack snapshots it parsed at startup. New requests to the supervisor still go through the old code path. The fix shipped in ga-a3ry.1 (binary drift detection in gc start) detects this automatically and restarts the supervisor. Resolution The gc start command in 1.1.0 detects the drift and offers to restart the supervisor. Confirm:
If the supervisor lifecycle is delegated to an operator-managed unit via GC_SUPERVISOR_SYSTEMD_UNIT (see “Delegating the Supervisor Lifecycle” in the troubleshooting guide), restart that unit instead: systemctl restart <unit>, with --user for user-scope units. The drift messages print the exact command for the configured unit. Verify after restart:
The reported buildID should match gc version.

​
  1. Duplicate agent name

Symptom
Cause Your pack declares [[agent]] blocks (legacy inline layout) for an agent name that another included pack declares in agents/<name>/agent.toml (current directory layout). Both contribute the same agent name; cross-pack agent name collisions are hard errors, so the validator refuses the ambiguity. The pack v1 → v2 mismatch line is emitted by ga-9ogb (collision detection); the source paths are filled in by ga-tpfc.1 (source-path ergonomics). Before 1.1.0, the second source rendered as an empty string. Resolution Choose one of the following.
The recommended path is migration. There is no fallback escape hatch: each pack must own its agents under unambiguous names, so any remaining cross-pack collision means one declaration must be renamed or removed. Background: Shareable Packs

​
  1. Unknown field

Symptom
Or any unknown field <path> error during pack parse. Cause Your pack.toml declares a field that the current gc binary’s schema does not recognise. The most common case in 1.1.0 is [agent.pool], removed in favour of flat min_active_sessions and max_active_sessions on the agent itself. Resolution Translate the deprecated block:
For current pack layout and import examples, see Shareable Packs.

​
  1. Rig path required

Symptom
Cause In earlier releases, rig paths could be inferred from a site.toml companion file. That mechanism is gone; city.toml is now the sole source of truth for rig locations. Resolution Add a path to each [[rigs]] entry in city.toml:
Run gc start to verify.

​
  1. Template not found

Symptom
Cause A [[named_session]] block in city.toml references an agent template (by name) that no loaded pack provides. The most common case: the relevant pack is missing from [city] includes. Resolution Add the pack to city.toml’s includes list:
If the template name is misspelled, fix the spelling. Verify with:

​
  1. Duplicate identity

Symptom
Cause The same agent template is declared as a [[named_session]] in both city.toml and a pack’s pack.toml. Each side claims ownership of the named-session identity; the validator refuses the collision. Resolution Remove the [[named_session]] from one side. The convention is to let the pack own the named-session identity and let city.toml override only when necessary:
If you need to override pack-provided behaviour, set the override fields in the pack’s named-session declaration directly, or extend the pack’s agent config rather than redeclaring the identity.

​
Still stuck?

  1. Run gc doctor --verbose and capture its output.
  2. Capture the failed gc start output:
  3. File an issue at gastownhall/gascity/issues with both attached, plus your OS / architecture and gc version.
Last modified on June 16, 2026