{"record":{"id":"6f0cfc59a985fa89","repo":"affaan-m/ECC","slug":"buildorchestrationplan-requires-at-least-one-worke","errorCode":null,"errorMessage":"buildOrchestrationPlan requires at least one worker","messagePattern":"buildOrchestrationPlan requires at least one worker","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"scripts/lib/tmux-worktree-orchestrator.js","lineNumber":190,"sourceCode":"  };\n}\n\nfunction buildOrchestrationPlan(config = {}) {\n  const repoRoot = path.resolve(config.repoRoot || process.cwd());\n  const repoName = path.basename(repoRoot);\n  const workers = Array.isArray(config.workers) ? config.workers : [];\n  const globalSeedPaths = normalizeSeedPaths(config.seedPaths, repoRoot);\n  const sessionName = slugify(config.sessionName || repoName, 'session');\n  const worktreeRoot = path.resolve(config.worktreeRoot || path.dirname(repoRoot));\n  const coordinationRoot = path.resolve(\n    config.coordinationRoot || path.join(repoRoot, '.orchestration')\n  );\n  const coordinationDir = path.join(coordinationRoot, sessionName);\n  const baseRef = config.baseRef || 'HEAD';\n  const defaultLauncher = config.launcherCommand || '';\n\n  if (workers.length === 0) {\n    throw new Error('buildOrchestrationPlan requires at least one worker');\n  }\n\n  const seenSlugs = new Set();\n  const workerPlans = workers.map((worker, index) => {\n    if (!worker || typeof worker.task !== 'string' || worker.task.trim().length === 0) {\n      throw new Error(`Worker ${index + 1} is missing a task`);\n    }\n\n    const workerName = worker.name || `worker-${index + 1}`;\n    const workerSlug = slugify(workerName, `worker-${index + 1}`);\n\n    if (seenSlugs.has(workerSlug)) {\n      throw new Error(`Workers must have unique slugs — duplicate: ${workerSlug}`);\n    }\n    seenSlugs.add(workerSlug);\n\n    const branchName = `orchestrator-${sessionName}-${workerSlug}`;\n    const worktreePath = path.join(worktreeRoot, `${repoName}-${sessionName}-${workerSlug}`);","sourceCodeStart":172,"sourceCodeEnd":208,"githubUrl":"https://github.com/affaan-m/ECC/blob/01e15490f04e29cfefe3896951f43db46994d8ee/scripts/lib/tmux-worktree-orchestrator.js#L172-L208","documentation":"Thrown by buildOrchestrationPlan() when config.workers is missing, not an array, or an empty array. The orchestrator's whole purpose is to fan out work across multiple tmux panes with one worker per pane, so a workerless plan has no effect and would produce a session with only the orchestrator pane. The check fires before any per-worker validation.","triggerScenarios":"Calling buildOrchestrationPlan({ repoRoot }) with no workers key; config.workers = [] ; config.workers = undefined (Array.isArray returns false, defaulting to []); config.workers = null; passing a single worker object instead of an array.","commonSituations":"A CLI default of workers: [] that the user never populates; a config template shipped with an empty workers array as a placeholder; programmatic use that builds the workers list conditionally and the condition is false; misreading the API and passing one worker object directly.","solutions":["Provide at least one worker: config.workers = [{ task: 'fix the failing tests', launcherCommand: 'claude \"{task_file}\"' }].","Validate before calling: if (!config.workers?.length) throw new Error('at least one worker required');","If your config builder can produce zero workers, branch around the call rather than letting buildOrchestrationPlan throw.","Wrap a single worker in an array rather than passing it bare."],"exampleFix":"// before\nbuildOrchestrationPlan({ repoRoot, launcherCommand, workers: [] });\n// -> buildOrchestrationPlan requires at least one worker\n\n// after\nbuildOrchestrationPlan({\n  repoRoot,\n  launcherCommand: 'claude \"{task_file}\"',\n  workers: [{ task: 'fix the failing tests' }],\n});","handlingStrategy":"validation","validationCode":"function assertWorkers(config) {\n  if (!Array.isArray(config.workers) || config.workers.length === 0) {\n    throw new Error('Orchestration requires at least one worker');\n  }\n}\n\nassertWorkers(config);\nbuildOrchestrationPlan(config);","typeGuard":"function hasWorkers(config) {\n  return !!config && Array.isArray(config.workers) && config.workers.length > 0;\n}","tryCatchPattern":"try {\n  buildOrchestrationPlan(config);\n} catch (error) {\n  if (/requires at least one worker/.test(error.message)) {\n    // nothing to do — surface a friendly message to the user\n    console.error('Add at least one worker to your orchestrator config.');\n    return;\n  }\n  throw error;\n}","preventionTips":["Validate the workers array at config load, not inside the orchestrator call.","Wrap single worker objects in an array before passing.","Treat zero workers as a user-facing config error and explain how to add one.","Default new CLI templates to a single placeholder worker so the user sees the shape."],"tags":["orchestration","configuration","validation","tmux"],"backgroundTag":null,"analyzedSha":"01e15490f04e29cfefe3896951f43db46994d8ee","analyzedAt":"2026-08-13T00:31:08.655Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}