Invalid platform "${platformRaw}" in --worker spec "${spec}"

Error message

Invalid platform "${platformRaw}" in --worker spec "${spec}". Use "claude" or "codex".

What it means

parseWorkerSpecs() variant thrown when the platform segment (text before the first colon, trimmed and lowercased) is neither 'claude' nor 'codex'. The dual-mode orchestrator only knows how to spawn these two worker platforms, and the platform decides which command template and prompt wrapper is used, so any other value is rejected before a worker is created.

Source

Thrown at v3/@claude-flow/codex/src/dual-mode/cli.ts:280

 */
export function parseWorkerSpecs(specs: string[], parallel: boolean): WorkerConfig[] {
  const usedIds = new Set<string>();
  const workers: WorkerConfig[] = [];

  specs.forEach((spec, index) => {
    const firstColon = spec.indexOf(':');
    const secondColon = firstColon >= 0 ? spec.indexOf(':', firstColon + 1) : -1;
    if (firstColon < 0 || secondColon < 0) {
      throw new Error(`Invalid --worker spec "${spec}". Expected "<platform>:<role>:<prompt>" (platform = claude|codex).`);
    }
    const platformRaw = spec.slice(0, firstColon).trim().toLowerCase();
    const role = spec.slice(firstColon + 1, secondColon).trim() || `worker-${index + 1}`;
    const prompt = spec.slice(secondColon + 1).trim();
    if (!prompt) {
      throw new Error(`Invalid --worker spec "${spec}". Missing prompt after "<platform>:<role>:".`);
    }
    if (platformRaw !== 'claude' && platformRaw !== 'codex') {
      throw new Error(`Invalid platform "${platformRaw}" in --worker spec "${spec}". Use "claude" or "codex".`);
    }
    const platform: 'claude' | 'codex' = platformRaw;

    // Derive a unique id from the role.
    const base = role.replace(/\s+/g, '-');
    let id = base;
    let suffix = 2;
    while (usedIds.has(id)) { id = `${base}-${suffix++}`; }
    usedIds.add(id);

    const worker: WorkerConfig = { id, platform, role, prompt };
    const prev = workers[workers.length - 1];
    if (!parallel && prev) {
      worker.dependsOn = [prev.id];
    }
    workers.push(worker);
  });

View on GitHub (pinned to fa13ee4ad6)

Solutions

Use exactly `claude` or `codex` as the first segment: `--worker "codex:coder:Implement the endpoint"`.
Double-check segment order — platform comes first, then role, then prompt.
The check is case-insensitive and whitespace-tolerant (trimmed/lowered), so fix only the value itself, not casing.
If you need a different tool, run it outside dual-mode or extend WorkerConfig platform support in code.

Example fix

# before
$ dual-mode collaborate --worker "opus:coder:Write the service layer"
Error: Invalid platform "opus" in --worker spec "opus:coder:Write the service layer". Use "claude" or "codex".

# after
$ dual-mode collaborate --worker "claude:coder:Write the service layer"

Defensive patterns

Strategy: validation

Validate before calling

const PLATFORMS = new Set(['claude', 'codex']);
function platformOf(spec: string): string | null {
  const first = spec.indexOf(':');
  if (first < 0) return null;
  const p = spec.slice(0, first).trim().toLowerCase();
  return PLATFORMS.has(p) ? p : null;
}
for (const spec of specs) {
  if (!platformOf(spec)) throw new Error(`platform must be claude|codex in: ${spec}`);
}
const workers = parseWorkerSpecs(specs, parallel);

Type guard

function isWorkerPlatform(v: unknown): v is 'claude' | 'codex' {
  return v === 'claude' || v === 'codex';
}

Try / catch

try {
  const workers = parseWorkerSpecs(specs, parallel);
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Invalid platform')) {
    throw new Error('segment order is <platform>:<role>:<prompt> with platform claude or codex — check you did not lead with the role');
  }
  throw err;
}

Prevention

Memorize the segment order: platform first — most bad-platform errors are transposed specs
The check is trim+lowercase, so casing never helps; only the values 'claude'/'codex' are accepted
Model names (opus, gpt-4) are not platforms — pick the harness that runs the model
Restrict spec generation to a helper that takes platform as a union type

When it happens

Trigger: (1) `--worker "gpt:coder:..."` or `--worker "cursor:coder:..."` — unsupported platform names; (2) typos like "calude" or "codez"; (3) segments in the wrong order, e.g. putting the role first ("reviewer:claude:...") so 'reviewer' is parsed as the platform.

Common situations: Assuming any CLI/tool name works as a worker; transposing segment order when writing specs by hand; naming the platform after a model ('opus', 'gpt-4') instead of the two supported harnesses.

Related errors

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