What causes "gbrain CLI not on PATH" in garrytan/gstack?

Install gbrain (run /setup-gbrain or the documented install command).

garrytan/gstack · error · Error

gbrain CLI not on PATH

Error message

gbrain CLI not on PATH

What it means

Thrown by probeSource() in gbrain-sources when execFileSync('gbrain', ...) fails with ENOENT or when stderr contains 'command not found'. It is the canonical 'gbrain is not installed / not on PATH' signal and is documented as one the caller should treat as 'source absent, skip stage' rather than a fatal error. The Windows .cmd shim handling is separate (NEEDS_SHELL_ON_WINDOWS).

Source

Thrown at lib/gbrain-sources.ts:131

 *   - "gbrain CLI not on PATH" (exit 127) — caller should treat as absent + skip stage.
 *   - "gbrain DB connection failed" — caller should treat as absent + skip stage.
 *   - JSON parse error — propagate via withErrorContext caller.
 */
export function probeSource(id: string, env?: NodeJS.ProcessEnv): SourceState {
  let stdout: string;
  try {
    stdout = execFileSync("gbrain", ["sources", "list", "--json"], {
      encoding: "utf-8",
      timeout: 30_000,
      stdio: ["ignore", "pipe", "pipe"],
      env,
      shell: NEEDS_SHELL_ON_WINDOWS, // #1731: gbrain is a .cmd shim on Windows
    });
  } catch (err) {
    const e = err as NodeJS.ErrnoException & { stderr?: Buffer };
    const stderr = e.stderr?.toString() || "";
    if (e.code === "ENOENT" || stderr.includes("command not found")) {
      throw new Error("gbrain CLI not on PATH");
    }
    if (stderr.includes("Cannot connect to database") || stderr.includes("config.json")) {
      throw new Error("gbrain not configured (run /setup-gbrain)");
    }
    throw err;
  }

  let parsed: unknown;
  try {
    parsed = JSON.parse(stdout);
  } catch (err) {
    throw new Error(`gbrain sources list returned non-JSON output: ${(err as Error).message}`);
  }

  const sources = parseSourcesList(parsed);
  const match = sources.find((s) => s.id === id);
  if (!match) return { status: "absent" };
  return {

View on GitHub (pinned to 94993f7401)

Solutions

Install gbrain (run /setup-gbrain or the documented install command).
Restart the shell or IDE so the updated PATH is picked up.
Verify with `which gbrain` (macOS/Linux) or `where gbrain` (Windows).
If installed elsewhere, symlink it onto PATH or add its bin dir to PATH.
In CI, add the gbrain install step before the job that calls probeSource.

Defensive patterns

Strategy: try-catch

Validate before calling

import { execFileSync } from 'child_process';
function gbrainOnPath(): boolean {
  try { execFileSync('which', ['gbrain'], { encoding: 'utf-8', stdio: 'ignore' }); return true; }
  catch { return false; }
}

Try / catch

try {
  return probeSource(id, env);
} catch (e) {
  if (e instanceof Error && e.message === 'gbrain CLI not on PATH') {
    // Non-fatal for sync flows: treat as absent and skip the stage
    return { status: 'absent' };
  }
  throw e;
}

Prevention

Run /setup-gbrain on every machine that executes sync flows.
Add a `which gbrain` check at workflow start.
Restart shells/IDEs after install so PATH updates apply.
In CI, install gbrain in the setup step before any sync job.

When it happens

Trigger: execFileSync cannot find a 'gbrain' executable on PATH (ENOENT), or the shell reports 'command not found' in stderr. Happens on machines that never installed gbrain, where gbrain was uninstalled, or where the install location is not on the current process PATH.

Common situations: Fresh machine without gbrain; gbrain installed under a different user so not on this user's PATH; a terminal/IDE launched before gbrain's installer updated PATH; a CI runner missing the gbrain setup step; nvm/asdf shell that didn't rehash after install.

Related errors

AI-assisted analysis of garrytan/gstack@94993f7401 (2026-08-12). Data as JSON: /api/errors/995b41a860fa9878. Report an issue: GitHub.