ruvnet/ruflo · error · Error

Unknown worker type: ${type}

Error message

Unknown worker type: ${type}

What it means

Thrown by WorkerDaemon.triggerWorker(type) when the given type has no entry in this.config.workers. config.workers is the daemon's built-in worker table (ultralearn, optimize, consolidate, predict, audit, map, preload, deepdive, document, refactor, benchmark, testgaps — plus backup/harness in the WorkerType union), so the type must be both a valid WorkerType AND present/enabled in the daemon's config. Note the trigger itself also awaits headlessInitPromise and bypasses the repository-supervisor gate (#2661), so the failure happens before any of that.

Source

Thrown at v3/@claude-flow/cli/src/services/worker-daemon.ts:2015

  /**
   * Local preload worker
   */
  private async runPreloadWorkerLocal(): Promise<unknown> {
    return {
      timestamp: new Date().toISOString(),
      mode: 'local',
      resourcesPreloaded: 0,
      cacheStatus: 'active',
    };
  }

  /**
   * Manually trigger a worker
   */
  async triggerWorker(type: WorkerType): Promise<WorkerResult> {
    const workerConfig = this.config.workers.find(w => w.type === type);
    if (!workerConfig) {
      throw new Error(`Unknown worker type: ${type}`);
    }
    // #2251 — wait for headless probe to settle before running. Without
    // this, on-demand `daemon trigger -w <worker>` races the constructor's
    // fire-and-forget init and ALWAYS falls through to local mode even
    // when `claude` is on PATH and scheduled fires of the same worker
    // use headless correctly. Scheduled fires already wait long enough
    // (timer + offset) that this is a no-op for them.
    await this.headlessInitPromise;
    // #2661 root-fix — an explicit manual trigger bypasses the repository-
    // supervisor gate (still budget/dedup-gated) — see runWorkerLogic()'s
    // doc comment.
    return this.executeWorker(workerConfig, { manualTrigger: true });
  }

  /**
   * Enable/disable a worker
   */
  setWorkerEnabled(type: WorkerType, enabled: boolean): void {

View on GitHub (pinned to fa13ee4ad6)

Solutions

1. Use one of the configured worker types: ultralearn, optimize, consolidate, predict, audit, map, preload, deepdive, document, refactor, benchmark, testgaps
2. List the daemon's actual workers (`daemon status` or the workers config) before triggering programmatically
3. If you need a custom worker type, add a matching WorkerConfig entry to the daemon config so config.workers.find() succeeds
4. Check for typos in the -w flag value — the error echoes the exact type it could not find

Example fix

// before
await daemon.triggerWorker('optimze' as WorkerType); // typo -> Unknown worker type: optimze

// after
await daemon.triggerWorker('optimize');

const daemon = getDaemon(projectRoot);
const configured = daemon.config.workers.map(w => w.type);
if (!configured.includes(requestedType)) {
  throw new Error(`Worker '${requestedType}' not configured. Available: ${configured.join(', ')}`);
}
await daemon.triggerWorker(requestedType as WorkerType);

import type { WorkerType } from './services/worker-daemon.js';

const DAEMON_WORKER_TYPES = [
  'ultralearn', 'optimize', 'consolidate', 'predict', 'audit', 'map',
  'preload', 'deepdive', 'document', 'refactor', 'benchmark', 'testgaps',
  'backup', 'harness',
] as const satisfies readonly WorkerType[];

function isDaemonWorkerType(value: unknown): value is WorkerType {
  return typeof value === 'string' && (DAEMON_WORKER_TYPES as readonly string[]).includes(value);
}

try {
  await daemon.triggerWorker(type);
} catch (e) {
  if (/^Unknown worker type:/.test(String(e?.message))) {
    // surface the configured list instead of the raw error
    const available = daemon.config.workers.map(w => w.type).join(', ');
    throw new Error(`Unknown worker type '${type}'. Configured workers: ${available}`);
  }
  throw e;
}

When it happens

Trigger: Calling daemon.triggerWorker('someType') or `claude-flow daemon trigger -w <type>` with a type not in the 12/14 built-in workers (typo like 'optimze', or a custom type the daemon was never configured with); passing a WorkerType union value such as 'backup' or 'harness' that is not in the default workers table.

Common situations: CLI users running `daemon trigger -w <name>` with a misspelled worker name; scripts assuming every WorkerType union member is triggerable; forks that extend WorkerType but forget to add a WorkerConfig entry; config filters that removed a worker from this.config.workers while a scheduler still references it.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Invalid completion type
• mode must be legacy, observe, or enforce
• Daemon not initialized. Provide projectRoot on first call.
• Invalid priority: ${priority}
• Worker config must include id

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