GAIA

Appearance

Troubleshooting ​

You'll learn the failures people actually run into with GAIA, what each one means, and the one thing that fixes it.

Each entry is symptom → cause → fix. When a symptom is not here, gaia conductor --log-level debug poll and gaia ui --print-config are the two commands that explain most of the rest.

gaia: command not found ​

Cause. npm's global bin directory is not on your PATH. Fix. npm prefix -g prints where npm installs; add its bin subdirectory to PATH. Verify with gaia --help.

no connection config could be loaded ​

Every gaia command fails with this line and a hint to point at a config.

Cause A — you are outside any project and the machine is not onboarded. There is no ./.gaia/gaia.config.js up the tree and no ~/.gaia/gaia.config.js. Fix. Run gaia conductor init --base-url <url> once to onboard the machine, or run the command inside a connected repository.

Cause B — the repository's config is newer than your CLI. The committed .gaia/gaia.config.js names an addon (in its addons list) that your installed version does not know; the loader gives up on the whole config. Fix. gaia update, then gaia upgrade. gaia version shows what you have.

gaia ui exits at once and prints nothing ​

Cause. The interactive cockpit re-executes itself under Bun, which ships with the CLI as an npm package. When that re-exec fails, nothing is drawn and nothing is said. Two things still run on Node and tell you the connection and the data are fine: gaia ui --print-config, and the non-interactive render

sh
GAIA_UI_NO_BUN=1 gaia ui GAIA-221 | cat

If that prints the ticket, the Bun runtime is the problem, not GAIA. Known causes: the bun package's post-install step was blocked, so its bin/bun.exe is still the placeholder; or a stale, dangling symlink under the CLI's node_modules that Bun resolves where Node would fail. Fix. Reinstall the CLI (npm install -g @gaia-ai/gaia@latest). In a source checkout, delete dangling links (find gaia-cli/node_modules -xtype l -delete) and run pnpm rebuild bun.

A write fails with 401 or "token expired" ​

Cause. Tokens are short-lived. gaia dropsh auth status shows each profile's validity. Fix. gaia dropsh auth login --provider session (or pm), then repeat the command. Prepare a long write before logging in, not after.

gaia dropsh search answers HTTP 404 ​

Cause. The entity type needs its bundle: search gaia_project without --bundle is not a valid JSON:API path. Fix. gaia dropsh search gaia_project --bundle gaia_project. The bundle is the same as the entity type for every GAIA entity except labels (gaia_term --bundle gaia_labels).

A ticket state write answers 403 with the session profile ​

Cause. The session scope is the agent's own identity: it may transition tickets it holds a claim on. Routing a ticket by hand from your shell is project-manager work. Fix. --auth-profile pm on the update.

A write answers 422 … format: The value you selected is not a valid choice ​

Cause. The role behind your profile may not use the gaia_rich text format — the only format GAIA uses for descriptions and comments. Fix. An administrator grants use text format gaia_rich to that role on the control plane.

My comment or description shows up empty ​

Cause. The body was HTML. gaia_rich is a Markdown format and strips raw HTML; the write succeeds and renders nothing. Fix. Write Markdown, and name format: gaia_rich on the write.

Nobody picks up my ticket ​

Work through the list; the first miss is the cause.

  1. Is the state claimable? done and cancelled never dispatch.
  2. Is it blocked? Every ticket in blocked_by must be closed.
  3. Which conductor is on it? A ticket is dispatched only to the conductor in its conductor_id; with none set it waits for a human. Set it in the cockpit's edit popup (e) or start the conductor it names.
  4. Is that conductor running? gaia conductor ls — offline or stale means no. Start it.
  5. Does the conductor's states list include this state? The generated engine config serves spec, diagnose, coding and review — not qualification. A hand-written ticket sits in qualification until a human or the create agent qualifies it, or until you add 'qualification' to states.
  6. Are its slots full? max_parallel in the engine config; the control plane's conductor list shows the load as 3/10.
  7. Is it parked? Three consecutive failed runs within two hours park a ticket until the window passes — see the failed entry below.

gaia conductor --log-level debug poll runs one tick and logs whether it claimed, was at capacity, or found nothing — it does not name the ticket it skipped, so the list above is the diagnosis.

The run sits in running and nothing happens ​

Cause A — the agent is waiting for you. A step that needs a decision asks in its terminal tab and stops; herdr marks the tab blocked. Fix. herdr tab list, find the tab named with the ticket identifier, answer there.

Cause B — the agent died without writing a state. A running run is never expired automatically, because the control plane cannot tell thinking from dead — and while it exists, the same state cannot be claimed again, so re-setting the conductor on the ticket changes nothing. Fix. Look at the tab; if the session is gone, move the ticket to a state the workflow allows from here, with the pm profile: requalify back to qualification from spec, diagnose or coding, or to_coding from review. The control plane retires the stuck run when the ticket leaves the state it was started for, and the conductor claims the new state at its next poll. The branch and worktree survive; the step is redone, not the work.

A run shows expired or failed ​

expired — a claim that was never started before its lease ran out; the ticket is claimable again and needs nothing from you. failed — dispatch threw before the agent could work, usually a worktree hook (an environment that did not come up) or a missing executor. Open the run on the ticket's Runs tab and read its Error log; fix the cause. The ticket is claimable again at once — unless it is parked: when a ticket's three most recent runs are all failed and the newest of them is under two hours old, the control plane stops handing it out, so a broken setup does not re-claim and re-fail every tick. Parking heals itself when the newest failure ages past the window or a run that did not fail appears among the last three; nothing needs a human, but until then the ticket waits.

Old worktrees pile up ​

Cause. Tickets that reached done while the conductor was down, or were reassigned, never got their worktree torn down. Fix. gaia conductor reap.

gaia ui talks to the wrong control plane ​

Cause. The connection is resolved from an explicit --config, then the project's .gaia/gaia.config.js, then your home config. You are in a repository that overrides the default, or outside every repository. Fix. gaia ui --print-config prints which file won and its base_url. Run the cockpit from the repository you mean, or pass --config.

gaia ui --here says no project owns the repository ​

Cause. The project's repos[] on the control plane does not list this checkout's origin remote (compared after normalising scheme, port and .git). Fix. Open it by name — gaia ui project:<name> — or have the project's repository URL added.

"A new gaia version is available" ​

Not an error. The conductor checks once a day. gaia update installs it, gaia upgrade migrates your config; --no-update-check on gaia conductor start silences the notice.

Next ​