ruvnet/ruflo · error

Unknown headless worker type

Error message

Unknown headless worker type: ${workerType}

What it means

execute() looked up workerType in the static HEADLESS_WORKER_CONFIGS table and got undefined — the caller asked for a worker kind that is not one of the registered headless worker types. Usually a typo, an unregistered variant, or a worker type added without a config entry.

Solutions

1. Use one of the supported headless worker types
2. Check the list of registered worker types before dispatch

Example fix

Use a supported headless worker type; check the executor's registered worker types and correct the --worker-type value.

When it happens

Trigger: Thrown at v3/@claude-flow/cli/src/services/headless-worker-executor.ts:756 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of ruvnet/ruflo@fa13ee4ad6 (2026-08-18). Data as JSON: /api/errors/3d971c443b51e19e. Report an issue: GitHub.

Appendix: source

Thrown at v3/@claude-flow/cli/src/services/headless-worker-executor.ts:756

  /**
   * Get Claude Code version
   */
  async getVersion(): Promise<string | null> {
    await this.isAvailable();
    return this.claudeCodeVersion;
  }

  /**
   * Execute a headless worker
   */
  async execute(
    workerType: HeadlessWorkerType,
    configOverrides?: Partial<HeadlessOptions>
  ): Promise<HeadlessExecutionResult> {
    const baseConfig = HEADLESS_WORKER_CONFIGS[workerType];
    if (!baseConfig) {
      throw new Error(`Unknown headless worker type: ${workerType}`);
    }

    // Check availability
    const available = await this.isAvailable();
    if (!available) {
      const result = this.createErrorResult(
        workerType,
        'Claude Code CLI not available. Install with: npm install -g @anthropic-ai/claude-code'
      );
      this.emit('error', result);
      return result;
    }

    // Check concurrent limit
    if (this.processPool.size >= this.config.maxConcurrent) {
      // Queue the request
      return new Promise((resolve, reject) => {
        const entry: QueueEntry = {

View on GitHub (pinned to fa13ee4ad6)