Yeachan-Heo/oh-my-codex · error · Error

detail || `background helper bootstrap exited ${bootstrap.st

Error message

detail || `background helper bootstrap exited ${bootstrap.status}`

What it means

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>'.

Source

Thrown at src/cli/index.ts:7553

          options.cwd,
        ),
      ],
      {
        cwd: options.cwd,
        encoding: "utf-8",
        stdio: ["ignore", "pipe", "pipe"],
        windowsHide: true,
        env: options.env,
      },
    );

    if (bootstrap.error) {
      throw bootstrap.error;
    }

    if (bootstrap.status !== 0) {
      const detail = (bootstrap.stderr || bootstrap.stdout || "").trim();
      throw new Error(
        detail || `background helper bootstrap exited ${bootstrap.status}`,
      );
    }

    const helperPid = Number.parseInt((bootstrap.stdout || "").trim(), 10);
    return Number.isFinite(helperPid) && helperPid > 0
      ? helperPid
      : undefined;
  }

  const child = spawn(process.execPath, helperArgs, {
    cwd: options.cwd,
    detached: shouldDetachBackgroundHelper(options.env, process.platform),
    stdio: "ignore",
    windowsHide: true,
    env: options.env,
  });
  child.unref();

View on GitHub (pinned to 3ad79a8a6f)

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

Defensive patterns

Strategy: try-catch

Validate before calling

const r = spawnSync(helperCmd, { encoding: 'utf8' });
if (r.status !== 0) console.error(r.stderr); // surface the real error before retrying

Try / catch

try { pid = await bootstrapHelper(); } catch (e) {
  const m = (e as Error).message;
  if (/bootstrap exited/.test(m)) { await killLeftoverHelpers(); pid = await bootstrapHelper(); }
  else throw e;
}

Prevention

Verify the helper binary exists on PATH after upgrades
Kill stale helper processes before starting
Capture stderr for diagnosis instead of discarding it

When it happens

Trigger: The spawned bootstrap process fails startup — missing binary/runtime, port or socket conflict, config error printed to stderr — and bootstrap.status !== 0.

Common situations: PATH issues after an upgrade, node/runtime version mismatch, leftover helper holding the socket, or sandboxed environments blocking the spawn.

Related errors

AI-assisted analysis of Yeachan-Heo/oh-my-codex@3ad79a8a6f (2026-08-27). Data as JSON: /api/errors/17fcdf4400d6c410. Report an issue: GitHub.