{"record":{"id":"9cd0a5fffaada1e0","repo":"affaan-m/ECC","slug":"program-args-join-failed-stderr","errorCode":null,"errorMessage":"${program} ${args.join(' ')} failed${stderr ? `: ${stderr}` : ''}","messagePattern":"(.+?) (.+?) failed(.+?)` : ''\\}","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"scripts/lib/tmux-worktree-orchestrator.js","lineNumber":336,"sourceCode":"    for (const file of artifacts.files) {\n      fs.writeFileSync(file.path, file.content + '\\n', 'utf8');\n    }\n  }\n}\n\nfunction runCommand(program, args, options = {}) {\n  const result = spawnSync(program, args, {\n    cwd: options.cwd,\n    encoding: 'utf8',\n    stdio: ['ignore', 'pipe', 'pipe']\n  });\n\n  if (result.error) {\n    throw result.error;\n  }\n  if (result.status !== 0) {\n    const stderr = (result.stderr || '').trim();\n    throw new Error(`${program} ${args.join(' ')} failed${stderr ? `: ${stderr}` : ''}`);\n  }\n  return result;\n}\n\nfunction commandSucceeds(program, args, options = {}) {\n  const result = spawnSync(program, args, {\n    cwd: options.cwd,\n    encoding: 'utf8',\n    stdio: ['ignore', 'pipe', 'pipe']\n  });\n  return result.status === 0;\n}\n\nfunction canonicalizePath(targetPath) {\n  const resolvedPath = path.resolve(targetPath);\n\n  try {\n    return fs.realpathSync.native(resolvedPath);","sourceCodeStart":318,"sourceCodeEnd":354,"githubUrl":"https://github.com/affaan-m/ECC/blob/01e15490f04e29cfefe3896951f43db46994d8ee/scripts/lib/tmux-worktree-orchestrator.js#L318-L354","documentation":"Thrown by runCommand() after spawnSync returns a non-zero exit status. The function wraps external programs (git, tmux) used by the orchestrator, and the error message includes the program, the joined args, and (if any) trimmed stderr so the caller can see the underlying tool's complaint. spawnSync's own spawn errors (binary not found) are re-thrown directly as result.error before this check.","triggerScenarios":"runCommand('git', ['worktree', 'add', '-b', branch, path, baseRef]) when baseRef does not exist; runCommand('git', ['branch', '-D', name]) on a branch that is currently checked out; runCommand('tmux', ['kill-session', '-t', name]) when no such session exists; runCommand('git', ['rev-parse', '--is-inside-work-tree']) outside a git repo; tmux subcommand fails because the server is not running.","commonSituations":"Calling executePlan outside a git working tree; baseRef configured to a branch that does not exist locally; a previous orchestrator run left state that conflicts; tmux not installed or not on PATH (though that usually surfaces as result.error first); permissions issue on the worktree root.","solutions":["Read the stderr in the message — it usually contains the exact tool complaint (e.g. 'fatal: ...').","For 'git worktree add' failures, run git worktree prune --expire now and check for an existing worktree at the target path.","For 'git branch -D' failures, switch off the branch first or use worktree remove which handles the association.","For tmux errors, verify the server with tmux ls and confirm the session name.","Prefer the orchestrator's cleanupExisting/replaceExisting flow over hand-rolled git commands when re-running."],"exampleFix":"// before (manual)\nrunCommand('git', ['worktree', 'add', '-b', branch, path, 'main']);\n// if 'main' does not exist locally: git worktree add ... failed: fatal: invalid reference: main\n\n// after\nrunCommand('git', ['fetch', 'origin', 'main:main'], { cwd: repoRoot });\nrunCommand('git', ['worktree', 'add', '-b', branch, path, 'main'], { cwd: repoRoot });\n// or pass replaceExisting: true and let executePlan clean up the prior run","handlingStrategy":"try-catch","validationCode":"function runCommandOrExplain(program, args, options = {}) {\n  const result = require('child_process').spawnSync(program, args, {\n    cwd: options.cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],\n  });\n  if (result.status === 0) return result;\n  const stderr = (result.stderr || '').trim();\n  throw new Error(`${program} ${args.join(' ')} exited ${result.status}: ${stderr}`);\n}\n\n// pre-flight checks\nif (!runCommand('git', ['rev-parse', '--is-inside-work-tree'], { cwd: repoRoot })) {\n  throw new Error(`${repoRoot} is not a git working tree`);\n}","typeGuard":"function commandSucceeds(program, args, options = {}) {\n  const result = require('child_process').spawnSync(program, args, {\n    cwd: options.cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],\n  });\n  return result.status === 0;\n}","tryCatchPattern":"try {\n  runCommand('git', ['worktree', 'add', '-b', branch, path, baseRef], { cwd: repoRoot });\n} catch (error) {\n  if (/git worktree add .* failed/.test(error.message)) {\n    // try to recover: prune and retry once with a fresh path\n    runCommand('git', ['worktree', 'prune', '--expire', 'now'], { cwd: repoRoot });\n    runCommand('git', ['worktree', 'add', '-b', branch, path, baseRef], { cwd: repoRoot });\n    return;\n  }\n  throw error;\n}","preventionTips":["Always pass cwd: repoRoot so git operates on the right repository.","Verify prerequisites (inside work tree, tmux installed, baseRef exists) before the real command.","Use replaceExisting: true when re-running executePlan so cleanup converges.","Parse stderr for the underlying tool message — it usually names the exact bad ref or path."],"tags":["orchestration","subprocess","git","tmux","external-command"],"backgroundTag":null,"analyzedSha":"01e15490f04e29cfefe3896951f43db46994d8ee","analyzedAt":"2026-08-13T00:31:08.655Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}