{"record":{"id":"3d971c443b51e19e","repo":"ruvnet/ruflo","slug":"unknown-headless-worker-type-workertype","errorCode":null,"errorMessage":"Unknown headless worker type: ${workerType}","messagePattern":"Unknown headless worker type: (.+?)","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/cli/src/services/headless-worker-executor.ts","lineNumber":756,"sourceCode":"\n  /**\n   * Get Claude Code version\n   */\n  async getVersion(): Promise<string | null> {\n    await this.isAvailable();\n    return this.claudeCodeVersion;\n  }\n\n  /**\n   * Execute a headless worker\n   */\n  async execute(\n    workerType: HeadlessWorkerType,\n    configOverrides?: Partial<HeadlessOptions>\n  ): Promise<HeadlessExecutionResult> {\n    const baseConfig = HEADLESS_WORKER_CONFIGS[workerType];\n    if (!baseConfig) {\n      throw new Error(`Unknown headless worker type: ${workerType}`);\n    }\n\n    // Check availability\n    const available = await this.isAvailable();\n    if (!available) {\n      const result = this.createErrorResult(\n        workerType,\n        'Claude Code CLI not available. Install with: npm install -g @anthropic-ai/claude-code'\n      );\n      this.emit('error', result);\n      return result;\n    }\n\n    // Check concurrent limit\n    if (this.processPool.size >= this.config.maxConcurrent) {\n      // Queue the request\n      return new Promise((resolve, reject) => {\n        const entry: QueueEntry = {","sourceCodeStart":738,"sourceCodeEnd":774,"githubUrl":"https://github.com/ruvnet/ruflo/blob/6b01dc5a687b26b3e218f796de45ec51f8fa9e8c/v3/@claude-flow/cli/src/services/headless-worker-executor.ts#L738-L774","documentation":"Thrown by HeadlessWorkerExecutor.execute() when the workerType argument is not a key in HEADLESS_WORKER_CONFIGS — i.e. not one of the eight valid headless worker types: 'audit', 'optimize', 'testgaps', 'document', 'ultralearn', 'refactor', 'deepdive', 'predict'. The lookup returns undefined for any other string (including valid LOCAL worker types like 'map', 'consolidate', 'benchmark', 'preload', which are handled by a different executor). This is a programming-error guard, not a runtime/recoverable condition.","triggerScenarios":"Calling executor.execute('map') or executor.execute('consolidate') (these are local workers, not headless); passing a typo like 'optimise' (British spelling) or 'test-gaps'; passing a custom worker name that was never registered; deserializing a workerType from untrusted config/queue data that contains an arbitrary string.","commonSituations":"Routing logic that forwards ALL worker types to the headless executor instead of branching on isHeadlessWorker()/isLocalWorker(); a queue or persisted config holding a worker type from a newer/older version that this build doesn't recognize; user-supplied worker type via a CLI flag without validation.","solutions":["Before calling execute(), narrow with isHeadlessWorker(type) — route local workers ('map','consolidate','benchmark','preload') to the local executor instead.","Validate the workerType against HEADLESS_WORKER_TYPES (the exported array) at the trust boundary (CLI parse, queue dequeue, config load).","Correct typos: the canonical spellings are 'optimize', 'testgaps', 'ultralearn', 'deepdive'."],"exampleFix":"// before\nawait executor.execute(workerConfig.type) // crashes for 'map'\n// after — branch on the worker category\nimport { isHeadlessWorker } from './headless-worker-executor.js';\nif (isHeadlessWorker(workerConfig.type)) {\n  await headlessExecutor.execute(workerConfig.type);\n} else {\n  await localExecutor.run(workerConfig.type);\n}","handlingStrategy":"type-guard","validationCode":"import { isHeadlessWorker, HEADLESS_WORKER_TYPES } from './headless-worker-executor.js';\nfunction safeExecute(executor: { execute: (t: string) => Promise<unknown> }, type: string) {\n  if (!isHeadlessWorker(type)) {\n    throw new Error(`'${type}' is not a headless worker. Valid: ${HEADLESS_WORKER_TYPES.join(', ')}`);\n  }\n  return executor.execute(type);\n}","typeGuard":"import { HEADLESS_WORKER_TYPES, type HeadlessWorkerType } from './headless-worker-executor.js';\nfunction isKnownHeadlessWorker(type: string): type is HeadlessWorkerType {\n  return (HEADLESS_WORKER_TYPES as string[]).includes(type);\n}","tryCatchPattern":"try {\n  await executor.execute(workerType as HeadlessWorkerType);\n} catch (e) {\n  if (e instanceof Error && /Unknown headless worker type/.test(e.message)) {\n    // the type came from untrusted data; validate against HEADLESS_WORKER_TYPES upstream\n    // and route local workers to the local executor\n  }\n  throw e;\n}","preventionTips":["Always narrow with isHeadlessWorker() before calling the headless executor; route the rest to the local executor.","Validate workerType at the trust boundary (CLI parse, queue dequeue, config load) against HEADLESS_WORKER_TYPES.","Never cast arbitrary strings to HeadlessWorkerType without a runtime check."],"tags":["worker-executor","api-misuse","type-narrowing","validation"],"backgroundTag":null,"analyzedSha":"6b01dc5a687b26b3e218f796de45ec51f8fa9e8c","analyzedAt":"2026-08-12T13:20:50.148Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}