{"record":{"id":"8ddf11cff263725c","repo":"coleam00/Archon","slug":"failed-to-start-detached-workflow-child-executabl","errorCode":null,"errorMessage":"Failed to start detached workflow child (executable: ${cmd[0]})","messagePattern":"Failed to start detached workflow child \\(executable: (.+?)\\)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"packages/cli/src/commands/workflow.ts","lineNumber":561,"sourceCode":"          : {}),\n      },\n      stdio: ['ignore', logFd ?? 'ignore', logFd ?? 'ignore'],\n      detached: true,\n      windowsHide: true,\n    });\n    // Unlike Bun.spawn, Node's spawn does NOT throw synchronously on a bad\n    // executable or cwd — the failure arrives as an async 'error' event, which\n    // would crash the CLI as an uncaught exception without this listener.\n    child.on('error', (error: Error) => {\n      getLog().error(\n        { err: error, execPath: cmd[0], conversationId },\n        'cli.detached_run_spawn_failed'\n      );\n    });\n    // pid is set synchronously iff the OS-level spawn succeeded (same check as\n    // setup.ts's trySpawn) — fail fast instead of acking a run that never started.\n    if (child.pid === undefined) {\n      throw new Error(`Failed to start detached workflow child (executable: ${cmd[0]})`);\n    }\n    await waitForDetachedStartup(child, logPath, cmd[0], conversationId);\n  } finally {\n    // The child inherits its own dup of the log fd; close the parent's copy so a\n    // synchronous spawn failure (bad execPath, invalid cwd) doesn't leak it.\n    if (logFd !== undefined) {\n      try {\n        closeSync(logFd);\n      } catch {\n        /* fd already closed/invalid — nothing to clean up */\n      }\n    }\n  }\n  return logPath;\n}\n\n/**\n * Parses the \"Source symlink at X already points to Y, expected Z\" error","sourceCodeStart":543,"sourceCodeEnd":579,"githubUrl":"https://github.com/coleam00/Archon/blob/0773b9745896ef0612e709c80845a0f7db315b19/packages/cli/src/commands/workflow.ts#L543-L579","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before: archon binary missing from PATH after an upgrade\n$ archon workflow run foo --detach\nError: Failed to start detached workflow child (executable: /usr/local/bin/archon)\n// after\n$ bun link   # or reinstall so /usr/local/bin/archon exists and is executable\n$ archon workflow run foo --detach","handlingStrategy":"try-catch","validationCode":"import { accessSync, constants } from 'fs';\n// before invoking --detach, confirm the executable exists and is executable\nconst exe = process.execPath; // or the archon binary path\ntry {\n  accessSync(exe, constants.X_OK);\n} catch {\n  throw new Error(`Cannot launch detached child: ${exe} missing or not executable`);\n}","typeGuard":null,"tryCatchPattern":"try {\n  await runWorkflow(name, { detach: true });\n} catch (e) {\n  if (String((e as Error).message).startsWith('Failed to start detached workflow child')) {\n    // inspect the run log file, verify the executable path, retry in foreground\n    console.error('Detached spawn failed; re-run in foreground to see the cause:', (e as Error).message);\n  }\n}","preventionTips":["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."],"tags":["process-spawn","detach","filesystem","cli"],"backgroundTag":"spawn-failed","analyzedSha":"0773b9745896ef0612e709c80845a0f7db315b19","analyzedAt":"2026-09-01T02:28:07.064Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}