{"record":{"id":"e0ebfcdb4c23c42c","repo":"JuliusBrussee/caveman","slug":"caveman-agent-cave-runtime-failed-to-start-err","errorCode":null,"errorMessage":"caveman agent: Cave Runtime failed to start (${error instanceof Error ? error.message : String(error)})","messagePattern":"caveman agent: Cave Runtime failed to start \\((.+?)\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/agent/src/runtime.ts","lineNumber":5240,"sourceCode":"        `cave_gateway_identity_unverified: non-loopback gateway ${gatewayURL} requires https`,\n      );\n    }\n    const identity = await gatewayIdentity(gatewayURL, fetchImpl);\n    if (identity !== undefined) return identity.providerBilling;\n    throw new Error(\n      `cave_gateway_identity_unverified: ${gatewayURL}/health/ready did not identify as caveman-proxy`,\n    );\n  }\n  const readyBilling = await runtimeReady(gatewayURL, fetchImpl);\n  if (readyBilling !== undefined) return readyBilling;\n\n  const command = process.env.CAVEMAN_CLI_BIN ?? \"caveman\";\n  let startupFailure: Error | undefined;\n  let invocation;\n  try {\n    invocation = portableInvocation(command, [\"start\"], { env: buildRuntimeControlEnv() });\n  } catch (error) {\n    throw new Error(`caveman agent: Cave Runtime failed to start (${error instanceof Error ? error.message : String(error)})`);\n  }\n  const child = spawn(invocation.command, [...invocation.args], {\n    detached: true,\n    windowsHide: true,\n    stdio: \"ignore\",\n    env: buildRuntimeControlEnv(),\n  });\n  child.once(\"error\", (error) => {\n    startupFailure = (error as NodeJS.ErrnoException).code === \"ENOENT\"\n      ? new Error(\n        \"caveman agent: Caveman CLI not found; run npm install, then caveman setup --install\",\n      )\n      : new Error(`caveman agent: Cave Runtime failed to start (${error.message})`);\n  });\n  child.once(\"exit\", (code, signal) => {\n    if (startupFailure !== undefined || code === 0) return;\n    startupFailure = new Error(\n      `caveman agent: Cave Runtime failed to start (caveman start exited ${signal ?? code}); run caveman setup --install`,","sourceCodeStart":5222,"sourceCodeEnd":5258,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/766dce6b1394ebb56a3090748d5a0240a5aefb36/packages/agent/src/runtime.ts#L5222-L5258","documentation":"Thrown when constructing the spawn invocation for `caveman start` itself fails — portableInvocation() threw before any child process existed, and the original error message is embedded. This is a CLI-resolution/platform problem, not a gateway problem: the runtime wanted to boot the loopback gateway but could not even build a valid command for the Caveman CLI binary (CAVEMAN_CLI_BIN, default \"caveman\").","triggerScenarios":"Loopback gateway is not ready, runtime tries portableInvocation(CAVEMAN_CLI_BIN ?? 'caveman', ['start'], ...) and that setup throws — e.g. the env-overridden CAVEMAN_CLI_BIN points somewhere unusable, or the invocation wrapper cannot be built on this platform/environment.","commonSituations":"CAVEMAN_CLI_BIN set to a wrong/nonexistent path in CI; partial npm/pnpm install where the caveman CLI shim exists but is broken; running in a minimal container where the spawn wrapper prerequisites (shell/path resolution) are missing.","solutions":["Unset or fix CAVEMAN_CLI_BIN so it names a working caveman executable (verify: caveman version)","Reinstall the runtime: caveman setup --install (or reinstall the package that ships the CLI)","Read the embedded parenthesized error — it carries the underlying failure (ENOENT-style path problems, permission, platform)","Run caveman doctor: it reports a missing runtime CLI as a WARN with execution_mode, confirming this layer before you debug the gateway"],"exampleFix":"# before\nexport CAVEMAN_CLI_BIN=/opt/broken/caveman # bad path\n\n# after\nunset CAVEMAN_CLI_BIN\ncaveman version && caveman setup --install","handlingStrategy":"validation","validationCode":"import { spawnSync } from 'node:child_process';\nfunction assertCavemanCLI() {\n  const bin = process.env.CAVEMAN_CLI_BIN ?? 'caveman';\n  const probe = spawnSync(bin, ['version'], { encoding: 'utf8' });\n  if (probe.error) throw new Error('caveman CLI unavailable: ' + bin);\n}","typeGuard":null,"tryCatchPattern":"try {\n  await run(agent, options);\n} catch (error) {\n  if (error instanceof Error && error.message.includes('Cave Runtime failed to start')) {\n    // embedded parenthesized reason carries the underlying invocation error\n    delete process.env.CAVEMAN_CLI_BIN; // fall back to the default binary\n    await reinstallRuntime(); // caveman setup --install\n    return run(agent, options);\n  }\n  throw error;\n}","preventionTips":["Pin CAVEMAN_CLI_BIN to an absolute path you have verified exists, or leave it unset","Run caveman setup --install in Dockerfiles/CI images so the CLI is present before any run","Include caveman doctor in environment validation; it flags a missing runtime CLI without spending a run"],"tags":["gateway","cli","spawn","startup","environment"],"backgroundTag":"process-spawn-failed","analyzedSha":"766dce6b1394ebb56a3090748d5a0240a5aefb36","analyzedAt":"2026-08-18T03:14:35.516Z","contentChangedAt":"2026-08-18T03:14:35.516Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}