[profile] ${profile.agent === "zcode" ? "ZCode" : "Codex"} A

Error message

[profile] ${profile.agent === "zcode" ? "ZCode" : "Codex"} App bot worker failed: ${formatError(error)}

What it means

Emitted on the 'error' event of a Codex/ZCode App bot worker child process: the process failed to spawn or errored at the OS level. The per-profile entry is removed from codexAppBotWorkers and the warning logged; other profiles' workers are unaffected.

Source

Thrown at packages/core/src/profiles/launch-service.ts:1489

    detached: false,
    env,
    stdio: ["ignore", "ignore", "pipe"],
    windowsHide: true,
    windowsVerbatimArguments: launch.windowsVerbatimArguments
  });
  codexAppBotWorkers.set(profile.id, { agent: profile.agent, child, stateDir: botEnv.CCR_BOT_GATEWAY_STATE_DIR });
  child.stderr?.on("data", (chunk) => {
    console.warn(`[profile] ${profile.agent === "zcode" ? "ZCode" : "Codex"} App bot worker stderr: ${chunk.toString("utf8").trim()}`);
  });
  child.once("exit", (code, signal) => {
    if (codexAppBotWorkers.get(profile.id)?.child === child) codexAppBotWorkers.delete(profile.id);
    if (code && code !== 0) {
      console.warn(`[profile] ${profile.agent === "zcode" ? "ZCode" : "Codex"} App bot worker exited: code=${code}${signal ? ` signal=${signal}` : ""}`);
    }
  });
  child.once("error", (error) => {
    if (codexAppBotWorkers.get(profile.id)?.child === child) codexAppBotWorkers.delete(profile.id);
    console.warn(`[profile] ${profile.agent === "zcode" ? "ZCode" : "Codex"} App bot worker failed: ${formatError(error)}`);
  });
}

function startCodexAppMediaPreviewBridge(
  config: AppConfig,
  profile: ReturnType<typeof findProfileForOpen>,
  userDataDir: string
): void {
  if (profile.agent !== "codex" || !shouldEnableCodexMediaPreviewBridge(config.mediaTools.enabled)) {
    stopCodexAppMediaPreviewBridge(profile.id);
    return;
  }
  const bridge = new CodexAppMediaPreviewBridge({
    endpoint: mediaToolsGatewayEndpoint(config),
    profileId: profile.id,
    userDataDir
  });
  const existing = codexAppMediaPreviewBridges.get(profile.id);

View on GitHub (pinned to 99f24806c6)

Solutions

Verify the Codex/ZCode executable for the failing profile exists and runs manually.
Reinstall the agent CLI for that profile or fix its configured path.
On Windows, quote/check the launcher path that uses verbatim arguments.
Restart the gateway after fixing so the worker respawns.

Defensive patterns

Strategy: try-catch

Validate before calling

null

Type guard

null

Try / catch

null

Prevention

Install per-profile agent binaries before enabling bot workers
Quote Windows launcher paths correctly
Restart the gateway after repairing the binary

When it happens

Trigger: Spawning the Codex/zcode bot worker for a profile fails — binary missing (ENOENT), not executable, or killed by the OS — triggering child.once('error').

Common situations: Codex CLI not installed for that profile; multi-profile setups where one profile's agent binary is absent while others work; Windows launcher issues with windowsVerbatimArguments paths.

Related errors

AI-assisted analysis of musistudio/claude-code-router@99f24806c6 (2026-08-27). Data as JSON: /api/errors/1b0a5f5825395e12. Report an issue: GitHub.