What causes "gbrain not configured (run /setup-gbrain)" in garrytan/gstack?

Run /setup-gbrain to initialize gbrain's config and database.

garrytan/gstack · error · Error

gbrain not configured (run /setup-gbrain)

Error message

gbrain not configured (run /setup-gbrain)

What it means

Thrown by probeSource() when gbrain ran (spawn succeeded) but its stderr indicates a configuration problem: 'Cannot connect to database' or a reference to 'config.json'. This means gbrain is installed but has not been initialized — the user needs to run /setup-gbrain to create its config and database before any sources command can work. Like 316, callers are expected to treat this as 'absent, skip stage' for non-fatal flows.

Source

Thrown at lib/gbrain-sources.ts:134

 */
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 {
    status: "match",
    registered_path: match.local_path,
  };

View on GitHub (pinned to 94993f7401)

Solutions

Run /setup-gbrain to initialize gbrain's config and database.
If config.json exists but is broken, back it up and re-run setup to regenerate.
Check permissions on gbrain's config/data directory (usually ~/.gbrain or similar).
Verify the database path in config.json resolves and is writable.

Defensive patterns

Strategy: try-catch

Validate before calling

import { execFileSync } from 'child_process';
function gbrainConfigured(env: NodeJS.ProcessEnv = process.env): boolean {
  try {
    execFileSync('gbrain', ['sources', 'list', '--json'], { encoding: 'utf-8', env, stdio: 'ignore', timeout: 5_000 });
    return true;
  } catch (e: any) {
    const stderr = e.stderr?.toString() ?? '';
    return !stderr.includes('Cannot connect to database') && !stderr.includes('config.json');
  }
}

Try / catch

try {
  return probeSource(id, env);
} catch (e) {
  if (e instanceof Error && e.message === 'gbrain not configured (run /setup-gbrain)') {
    return { status: 'absent' }; // skip stage, prompt user to run setup
  }
  throw e;
}

Prevention

Run /setup-gbrain once per environment to initialize config + DB.
Verify config.json path and DB permissions after setup.
Back up gbrain's config before OS migrations.
Treat this as a skip-stage signal in non-fatal sync flows.

When it happens

Trigger: gbrain sources list --json exits non-zero with stderr containing 'Cannot connect to database' or 'config.json'. The CLI binary exists but its backing database/config is missing or unreadable.

Common situations: gbrain installed but /setup-gbrain never run; the database file was deleted or moved; config.json corrupted or points at an unreachable DB path; permissions on the gbrain config dir prevent reading.

Related errors

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