What causes "[profile] Claude App bot worker failed: ${formatError(error)}" in musistudio/claude-code-router?

Verify the worker executable exists and is runnable from the same environment (run it manually).

[profile] Claude App bot worker failed: ${formatError(error)

Error message

[profile] Claude App bot worker failed: ${formatError(error)}

What it means

Emitted on the child process 'error' event for the Claude App bot worker: the process could not be spawned, was killed, or failed to communicate (spawn ENOENT, EACCES, or signal death). The module-level worker references are cleared and the gateway continues without the bot worker.

Source

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

    console.warn(`[profile] Claude App bot worker stderr: ${chunk.toString("utf8").trim()}`);
  });
  child.once("exit", (code, signal) => {
    if (claudeAppBotWorker === child) {
      claudeAppBotWorker = undefined;
      claudeAppBotWorkerProfileId = undefined;
      claudeAppBotWorkerStateDir = undefined;
    }
    if (code && code !== 0) {
      console.warn(`[profile] Claude App bot worker exited: code=${code}${signal ? ` signal=${signal}` : ""}`);
    }
  });
  child.once("error", (error) => {
    if (claudeAppBotWorker === child) {
      claudeAppBotWorker = undefined;
      claudeAppBotWorkerProfileId = undefined;
      claudeAppBotWorkerStateDir = undefined;
    }
    console.warn(`[profile] Claude App bot worker failed: ${formatError(error)}`);
  });
}

function startOpenCodeAppBotWorker(
  config: AppConfig,
  profile: ReturnType<typeof findProfileForOpen>,
  configFile: string,
  inlineConfig: string,
  launchSignature: string
): void {
  const botEnv = botGatewayProfileEnv(config, profile, "app");
  if (botEnv.CCR_BOT_GATEWAY_ENABLED !== "true") {
    stopOpenCodeAppBotWorker(profile.id);
    return;
  }
  if (
    openCodeAppBotWorker &&
    !openCodeAppBotWorker.killed &&

View on GitHub (pinned to 99f24806c6)

Solutions

Verify the worker executable exists and is runnable from the same environment (run it manually).
Reinstall/repair the Claude app/CLI so its runtime path resolves.
Check permissions and, on Windows, antivirus interference with the child process.
Confirm the gateway profile env (bot worker state dir, node path) is set for the launching user.

Defensive patterns

Strategy: try-catch

Validate before calling

null

Type guard

null

Try / catch

null

Prevention

Verify the Claude worker binary is installed and on PATH
Check executable permissions
Ensure required gateway env vars are present when spawning

When it happens

Trigger: startClaudeAppBotWorker spawns the worker but the binary cannot be found (ENOENT), is not executable (EACCES), or the process errors before exit handling — the once('error') handler fires.

Common situations: Claude CLI/app binary missing from PATH or not installed; permissions problem on the executable; node runtime path (CCR_CLI_NODE_PATH-style) invalid; antivirus/OS killing the child on Windows.

Related errors

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