{"record":{"id":"995b41a860fa9878","repo":"garrytan/gstack","slug":"gbrain-cli-not-on-path","errorCode":null,"errorMessage":"gbrain CLI not on PATH","messagePattern":"gbrain CLI not on PATH","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"lib/gbrain-sources.ts","lineNumber":131,"sourceCode":" *   - \"gbrain CLI not on PATH\" (exit 127) — caller should treat as absent + skip stage.\n *   - \"gbrain DB connection failed\" — caller should treat as absent + skip stage.\n *   - JSON parse error — propagate via withErrorContext caller.\n */\nexport function probeSource(id: string, env?: NodeJS.ProcessEnv): SourceState {\n  let stdout: string;\n  try {\n    stdout = execFileSync(\"gbrain\", [\"sources\", \"list\", \"--json\"], {\n      encoding: \"utf-8\",\n      timeout: 30_000,\n      stdio: [\"ignore\", \"pipe\", \"pipe\"],\n      env,\n      shell: NEEDS_SHELL_ON_WINDOWS, // #1731: gbrain is a .cmd shim on Windows\n    });\n  } catch (err) {\n    const e = err as NodeJS.ErrnoException & { stderr?: Buffer };\n    const stderr = e.stderr?.toString() || \"\";\n    if (e.code === \"ENOENT\" || stderr.includes(\"command not found\")) {\n      throw new Error(\"gbrain CLI not on PATH\");\n    }\n    if (stderr.includes(\"Cannot connect to database\") || stderr.includes(\"config.json\")) {\n      throw new Error(\"gbrain not configured (run /setup-gbrain)\");\n    }\n    throw err;\n  }\n\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(stdout);\n  } catch (err) {\n    throw new Error(`gbrain sources list returned non-JSON output: ${(err as Error).message}`);\n  }\n\n  const sources = parseSourcesList(parsed);\n  const match = sources.find((s) => s.id === id);\n  if (!match) return { status: \"absent\" };\n  return {","sourceCodeStart":113,"sourceCodeEnd":149,"githubUrl":"https://github.com/garrytan/gstack/blob/94993f74012782fd94416dd44b8314f6363a13a4/lib/gbrain-sources.ts#L113-L149","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"import { execFileSync } from 'child_process';\nfunction gbrainOnPath(): boolean {\n  try { execFileSync('which', ['gbrain'], { encoding: 'utf-8', stdio: 'ignore' }); return true; }\n  catch { return false; }\n}","typeGuard":null,"tryCatchPattern":"try {\n  return probeSource(id, env);\n} catch (e) {\n  if (e instanceof Error && e.message === 'gbrain CLI not on PATH') {\n    // Non-fatal for sync flows: treat as absent and skip the stage\n    return { status: 'absent' };\n  }\n  throw e;\n}","preventionTips":["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."],"tags":["gbrain","cli","path","environment","setup"],"backgroundTag":null,"analyzedSha":"94993f74012782fd94416dd44b8314f6363a13a4","analyzedAt":"2026-08-12T04:06:23.140Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}