{"record":{"id":"17fcdf4400d6c410","repo":"Yeachan-Heo/oh-my-codex","slug":"detail-background-helper-bootstrap-exited-bo","errorCode":null,"errorMessage":"detail || `background helper bootstrap exited ${bootstrap.status}`","messagePattern":"detail \\|\\| `background helper bootstrap exited (.+?)`","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/cli/index.ts","lineNumber":7553,"sourceCode":"          options.cwd,\n        ),\n      ],\n      {\n        cwd: options.cwd,\n        encoding: \"utf-8\",\n        stdio: [\"ignore\", \"pipe\", \"pipe\"],\n        windowsHide: true,\n        env: options.env,\n      },\n    );\n\n    if (bootstrap.error) {\n      throw bootstrap.error;\n    }\n\n    if (bootstrap.status !== 0) {\n      const detail = (bootstrap.stderr || bootstrap.stdout || \"\").trim();\n      throw new Error(\n        detail || `background helper bootstrap exited ${bootstrap.status}`,\n      );\n    }\n\n    const helperPid = Number.parseInt((bootstrap.stdout || \"\").trim(), 10);\n    return Number.isFinite(helperPid) && helperPid > 0\n      ? helperPid\n      : undefined;\n  }\n\n  const child = spawn(process.execPath, helperArgs, {\n    cwd: options.cwd,\n    detached: shouldDetachBackgroundHelper(options.env, process.platform),\n    stdio: \"ignore\",\n    windowsHide: true,\n    env: options.env,\n  });\n  child.unref();","sourceCodeStart":7535,"sourceCodeEnd":7571,"githubUrl":"https://github.com/Yeachan-Heo/oh-my-codex/blob/3ad79a8a6fe6e95fdbb8c00e40716fffe4011ce2/src/cli/index.ts#L7535-L7571","documentation":"A background helper bootstrap subprocess exited non-zero (or its error was rethrown); the message prefers trimmed stderr/stdout and falls back to 'background helper bootstrap exited <status>'.","triggerScenarios":"The spawned bootstrap process fails startup — missing binary/runtime, port or socket conflict, config error printed to stderr — and bootstrap.status !== 0.","commonSituations":"PATH issues after an upgrade, node/runtime version mismatch, leftover helper holding the socket, or sandboxed environments blocking the spawn.","solutions":["Run the same bootstrap command manually to see the real stderr (the message usually contains it)","Fix the reported root cause (missing dependency, occupied socket/port, permissions)","Kill leftover background helper processes and retry the bootstrap"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"const r = spawnSync(helperCmd, { encoding: 'utf8' });\nif (r.status !== 0) console.error(r.stderr); // surface the real error before retrying","typeGuard":null,"tryCatchPattern":"try { pid = await bootstrapHelper(); } catch (e) {\n  const m = (e as Error).message;\n  if (/bootstrap exited/.test(m)) { await killLeftoverHelpers(); pid = await bootstrapHelper(); }\n  else throw e;\n}","preventionTips":["Verify the helper binary exists on PATH after upgrades","Kill stale helper processes before starting","Capture stderr for diagnosis instead of discarding it"],"tags":["subprocess","bootstrap","background-helper"],"backgroundTag":"subprocess-exit-nonzero","analyzedSha":"3ad79a8a6fe6e95fdbb8c00e40716fffe4011ce2","analyzedAt":"2026-08-27T22:18:39.783Z","schemaVersion":2},"datasetVersion":"2026-08-28T00:17:15.603Z"}