coleam00/Archon · critical · Error

Failed to start detached workflow child (executable: ${cmd[0

Error message

Failed to start detached workflow child (executable: ${cmd[0]})

What it means

spawnDetachedWorkflowRun() forks the workflow run as a detached child process (e.g. for --detach). Bun's spawn only sets child.pid if the OS-level spawn succeeded; if pid is undefined the CLI throws this error and rolls back the event ('cli.detached_run_spawn_failed') instead of acknowledging a run that never started. It means the executable in cmd[0] could not be launched at all.

Source

Thrown at packages/cli/src/commands/workflow.ts:561

          : {}),
      },
      stdio: ['ignore', logFd ?? 'ignore', logFd ?? 'ignore'],
      detached: true,
      windowsHide: true,
    });
    // Unlike Bun.spawn, Node's spawn does NOT throw synchronously on a bad
    // executable or cwd — the failure arrives as an async 'error' event, which
    // would crash the CLI as an uncaught exception without this listener.
    child.on('error', (error: Error) => {
      getLog().error(
        { err: error, execPath: cmd[0], conversationId },
        'cli.detached_run_spawn_failed'
      );
    });
    // pid is set synchronously iff the OS-level spawn succeeded (same check as
    // setup.ts's trySpawn) — fail fast instead of acking a run that never started.
    if (child.pid === undefined) {
      throw new Error(`Failed to start detached workflow child (executable: ${cmd[0]})`);
    }
    await waitForDetachedStartup(child, logPath, cmd[0], conversationId);
  } finally {
    // The child inherits its own dup of the log fd; close the parent's copy so a
    // synchronous spawn failure (bad execPath, invalid cwd) doesn't leak it.
    if (logFd !== undefined) {
      try {
        closeSync(logFd);
      } catch {
        /* fd already closed/invalid — nothing to clean up */
      }
    }
  }
  return logPath;
}

/**
 * Parses the "Source symlink at X already points to Y, expected Z" error

View on GitHub (pinned to 0773b97458)

Solutions

Verify the executable named in the message exists and is executable (`which <cmd[0]>; ls -l $(which <cmd[0]>)`).
Check the workflow log file (logPath) for the underlying spawn failure detail before the finally block closed it.
Reinstall/repair the archon binary if it was replaced mid-run.
Re-run the workflow in the foreground (--no-detach equivalent) to see the failure directly.
Check ulimit -u / process limits if on a constrained host.

Example fix

// before: archon binary missing from PATH after an upgrade
$ archon workflow run foo --detach
Error: Failed to start detached workflow child (executable: /usr/local/bin/archon)
// after
$ bun link   # or reinstall so /usr/local/bin/archon exists and is executable
$ archon workflow run foo --detach

Defensive patterns

Strategy: try-catch

Validate before calling

import { accessSync, constants } from 'fs';
// before invoking --detach, confirm the executable exists and is executable
const exe = process.execPath; // or the archon binary path
try {
  accessSync(exe, constants.X_OK);
} catch {
  throw new Error(`Cannot launch detached child: ${exe} missing or not executable`);
}

Try / catch

try {
  await runWorkflow(name, { detach: true });
} catch (e) {
  if (String((e as Error).message).startsWith('Failed to start detached workflow child')) {
    // inspect the run log file, verify the executable path, retry in foreground
    console.error('Detached spawn failed; re-run in foreground to see the cause:', (e as Error).message);
  }
}

Prevention

Never delete/replace the archon binary while detached runs may start.
Keep the working directory valid for the lifetime of the command.
Check ulimit -u on constrained hosts before bulk detached runs.
Confirm `which archon` resolves to an executable after upgrades.

When it happens

Trigger: Bun.spawn of the detached child fails synchronously — the executable path (cmd[0], usually the archon binary or bun) does not exist or is not executable, the cwd is invalid, or resource limits (EAGAIN/fork failure) prevent process creation.

Common situations: Binary was updated/deleted between invocation and spawn; PATH/executable resolution broke inside an installer or container; bad execPath configured; cwd removed before spawn; ulimit -u exhausted on shared hosts.

Related errors

AI-assisted analysis of coleam00/Archon@0773b97458 (2026-09-01). Data as JSON: /api/errors/8ddf11cff263725c. Report an issue: GitHub.