Troubleshooting

Start here whenever gald3r isn't behaving the way you expect. Every command and output shape on this page was verified against a real checkout while writing it — including the warnings, not just the happy path — with placeholders only where a value (a version number, a percentage) would otherwise go stale the moment the next release ships.

Step 1: gald3r doctor

gald3r doctor

doctor checks your identity file, schema version, any installed IDE overlay's freshness, PATH resolution (a stale or shadowing gald3r copy earlier on PATH), platform-spec parity, wired hooks, git-hooks configuration, declared constraints, and the local task/bug database's consistency against the files on disk — all in one pass. warn/skip rows are informational, never a blocking failure by themselves; fail rows always name the exact fix to run. A few worth knowing:

Row	What it means	Fix
schema_version	The binary's expected schema/rel version doesn't match this project's .identity	gald3r schema-migrate to bring the project forward, or use a matching binary version
overlay_currency / overlay_version_stamp	An installed platform overlay (.claude/, .cursor/) has drifted from what the current binary would generate, or was stamped by a different version	gald3r platform install <platform> --force to resync
path_resolution	More than one gald3r binary is reachable on PATH, and they disagree	Remove or reorder the stale copy so the current one resolves first — the check names the exact path and remediation command
git_hooks	core.hooksPath isn't pointed at this repo's .githooks/	git config core.hooksPath .githooks if you want local pre-commit checks enabled

world_tree connectivity and stored-session-token status aren't part of doctor's default pass — check them directly with gald3r workspace probe and gald3r workspace token-status. Neither being unset blocks anything outside team/cross-project features — gald3r login signs in when you need them.

Step 2: gald3r selftest

gald3r selftest

gald3r system test harness -- <project> (gald3r <version>)
Overall: N% functional (M/K passing)
  [PASS   ] Bug Tracking             100%
  [FAIL   ] PLATFORM_SPEC            0%
  [FAIL   ] Platform Parity          0%
  [SKIP   ] Hook Wiring              -
  [FAIL   ] Git Hooks                0%
  [SKIP   ] Constraints              -
Report: <project>\.gald3r\reports\system_test_<timestamp>.md

selftest is a percentage-of-installed-capability check, not a pass/fail gate — a lower number usually means no platform overlay is installed yet in this particular project (platform parity, hook wiring, and git hooks all depend on one), not that the CLI itself is broken. Read the written report file for exactly which sub-checks failed and why; install a platform overlay (gald3r platform install <name>) and re-run if those are the checks you care about.

Step 3: gald3r errors / gald3r trace

gald3r errors

No matching error/failure trace records.

(Real output — a clean checkout has none.) When something DID fail during an agent run, errors summarizes it from the trace logs; gald3r trace inspects the full trace log directly for a specific run.

Step 4: gald3r medic

gald3r medic --help

Diagnose and repair problems in your project's gald3r setup -- broken links, stale indexes,
drifted files -- fixing what's safe to fix automatically.

Available Commands:
  curate      Analyze feature/subsystem fragmentation (dry-run) or apply approved moves
  heal        Structural backfill for repos predating a framework feature (dry-run default)

medic diagnoses and repairs problems in your project's .gald3r/ structure itself — broken links, stale indexes, drifted files — fixing what's safe to fix automatically and reporting the rest. Both subcommands default to dry-run; nothing changes on disk until you pass the apply flag they document.

Common issues

Windows: gald3r returns instantly with no output at all (blank exit code)

If you hit this, you're almost certainly invoking gald3rw.exe directly (the GUI-attach binary) from a console-less host, or you have a stale single-binary install still on PATH. Update to the current release (gald3r install update, or re-run gald3r platform install if you're on an installed overlay) and invoke gald3r, not gald3rw, from a shell.

The two-exe contract: the Windows release ships TWO executables on PATH:

Binary	PE subsystem	Use it for
gald3r.exe	Console (3)	Terminals, scripts, scheduled tasks, AI-agent shells — anywhere you type gald3r yourself or a script invokes it directly. Always waits, always prints, always returns a real exit code — including from a console-less PowerShell host.
gald3rw.exe	GUI (2), attach	Throne, IDE hooks, the Valkyrie connector, and any other spawn from a process that must never flash a console window. Interactive terminal usage still prints normally; a console-less parent gets zero console flash and no output — by design, since nothing is watching for it there.

If you are deliberately invoking gald3rw.exe yourself (uncommon — it exists for programmatic/GUI-parented spawns, not interactive use) and want its output anyway, any of these forms works:

cmd /c "gald3rw --version"          # cmd allocates a console; output flows normally

Start-Process gald3rw -ArgumentList "--version" -NoNewWindow -Wait `
  -RedirectStandardOutput out.txt   # explicit handles bypass console attachment

Normal interactive terminals (Windows Terminal, VS Code/Cursor terminal panels, cmd.exe, Git Bash) and CI runners are unaffected either way.

"gald3r: command not found" / binary not on PATH

You installed the signed release but its install directory isn't on PATH, or you edited PATH in a terminal that was already open. See install.md — and fully restart your terminal/IDE after any PATH edit. If you built from source, see Install → From source for the equivalent PATH-registration step.

Installed platform overlay (.claude/, .cursor/) looks stale or hooks aren't firing

gald3r doctor

[warn] overlay_currency  claude: stale -- marker binary_version=5.0.0-beta.21 vs running
       5.0.0-beta.28; overlay_content_hash differs from the embedded neutral_source's
       current hash -- run `gald3r platform install claude --force` to refresh

(Real output shape, trimmed.) This is the platform-overlay drift check — the files actually on disk in .claude//.cursor/ no longer match what gald3r platform install would generate today (you hand-edited an installed file, or you upgraded the gald3r binary since you last installed the overlay). Fix:

gald3r platform install claude --into . --force

--force overwrites the drifted files with a fresh render — including a fresh, non-destructive .claude/settings.json merge (see install.md), so your own mcpServers/permissions/other top-level keys survive even across a forced resync.

gald3r status says "No .gald3r/gald3r.db found yet"

Expected on a fresh checkout, or after cloning a repo where the DB (gitignored by design — it's a regeneratable cache, not source of truth for the files) wasn't carried over:

gald3r db backfill

rebuilds it from the .gald3r/tasks/ and .gald3r/bugs/ files. See task-bug-workflow.md.

A task/bug file won't pass gald3r validate

gald3r validate --fix

normalizes whatever's safely auto-fixable (missing-but-inferable frontmatter fields, open-family files still sitting in a retired tasks/<old-status>/ or bugs/<old-status>/ subfolder). Anything it can't safely fix on its own, it reports instead of guessing. Active records belong at the tasks/ / bugs/ root; only completed//failed//cancelled/ (tasks) and done//cancelled/ (bugs) remain as terminal folders.

An autopilot/swarm run looks stuck

gald3r go-status

Read-only check on whether a running autopilot loop is ALIVE, IDLE-WAIT, STALLED, or STOPPED — without interrupting it. See autopilot.md for the rest of the run-management verbs (autopilot stop, worktree steer/queue).

gald3r login fails or times out

gald3r login

gald3r login with no arguments starts an interactive device-code sign-in: it requests a code from world_tree, prints a verification URL plus a short code for you to enter in any browser, polls until you approve, and stores the resulting session token — no raw token handling needed. If the sign-in service is temporarily unreachable, login fails loudly with the underlying error rather than hanging silently; retry, or use a pre-issued Bearer token instead if you have one:

gald3r login --token <TOKEN>                              # one-off
gald3r login --token <TOKEN> --base-url https://api.gald3r.ai   # explicit API base (default shown)

$GALD3R_WORLD_TREE_TOKEN is the equivalent env-var form, useful in CI or so you don't have to pass --token by hand every time. gald3r logout clears whatever session is currently stored (gald3r logout: no stored session to clear if there wasn't one — also not an error). None of this is required for local, single-project use — gald3r workspace token-status reports whether a session is stored, and a missing one only matters once you're using world_tree-backed features (valk, cross-project workspace sync, version-check's online path). See coordination.md for what those features actually unlock.

Cross-project coordination looks out of sync

gald3r workspace probe
gald3r workspace outbox pull

See coordination.md for the full WPAC/Valkyrie model — most drift is resolved by outbox pull reconciling the local mirror against the online registry.

Where next

gald3r <verb> --help (and gald3r <verb> <subverb> --help) is always more authoritative than this page for any single verb's current flags — if this page and --help ever disagree, trust --help.