What causes "Unknown template: ${template}" in ruvnet/ruflo?

Use one of the three supported template names: feature, security, refactor (lowercase).

Unknown template: ${template}

Error message

Unknown template: ${template}

What it means

getTemplateWorkers() maps the template argument of the dual-mode run command to a canned worker pipeline via a switch with exactly three cases: 'feature' (featureDevelopment), 'security' (securityAudit), and 'refactor' (refactoring). Any other template string falls through to default and throws — there is no fuzzy matching or listing fallback.

Source

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

    workers.push(worker);
  });

  return workers;
}

/**
 * Get workers for a template
 */
function getTemplateWorkers(template: string, task: string): WorkerConfig[] {
  switch (template) {
    case 'feature':
      return CollaborationTemplates.featureDevelopment(task);
    case 'security':
      return CollaborationTemplates.securityAudit(task);
    case 'refactor':
      return CollaborationTemplates.refactoring(task);
    default:
      throw new Error(`Unknown template: ${template}`);
  }
}

/**
 * Print collaboration results
 */
function printResults(result: CollaborationResult): void {
  console.log(chalk.bold('Results:'));
  console.log(`  Status: ${result.success ? chalk.green('SUCCESS') : chalk.red('FAILED')}`);
  console.log(`  Duration: ${(result.totalDuration / 1000).toFixed(2)}s`);
  console.log();

  console.log(chalk.bold('Worker Summary:'));
  for (const worker of result.workers) {
    const status = worker.status === 'completed' ? chalk.green('✓') :
                   worker.status === 'failed' ? chalk.red('✗') :
                   chalk.yellow('○');
    const duration = worker.startedAt && worker.completedAt

View on GitHub (pinned to fa13ee4ad6)

Solutions

Use one of the three supported template names: feature, security, refactor (lowercase).
For any other workflow, skip templates and pass explicit --worker specs, which accept arbitrary roles and prompts.
Run the templates listing (the `templates` subcommand) to see the current built-ins.
Check spelling/case — the switch is exact-match.

Example fix

# before
$ dual-mode run refactoring "clean up utils"
Error: Unknown template: refactoring

# after
$ dual-mode run refactor "clean up utils"
# or, for a custom pipeline:
$ dual-mode collaborate --parallel --worker "claude:analyst:Map utils usage" --worker "codex:coder:Apply the cleanup"

Defensive patterns

Strategy: validation

Validate before calling

const KNOWN_TEMPLATES = new Set(['feature', 'security', 'refactor']);
if (!KNOWN_TEMPLATES.has(template)) {
  throw new Error(`unknown template "${template}" — use one of ${[...KNOWN_TEMPLATES].join(', ')}, or pass explicit --worker specs`);
}
const workers = getTemplateWorkers(template, task);

Type guard

function isKnownTemplate(v: string): v is 'feature' | 'security' | 'refactor' {
  return v === 'feature' || v === 'security' || v === 'refactor';
}

Try / catch

try {
  const workers = getTemplateWorkers(template, task);
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Unknown template:')) {
    // degrade gracefully: fall back to an explicit worker pipeline
    return explicitWorkers(task);
  }
  throw err;
}

Prevention

Pin template names to constants in scripts instead of free-form user input
Check the templates listing when upgrading — the supported set is exactly feature/security/refactor
For anything beyond the three built-ins, switch to --worker specs which accept arbitrary roles
Match case exactly; the switch is not normalized

When it happens

Trigger: (1) `dual-mode run review "..."` or `dual-mode run docs "..."` — a task kind that is not one of the three built-ins; (2) typos like 'features', 'Security' (case-sensitive match), or 'refactoring' instead of 'refactor'; (3) assuming any skill/agent name from the wider claude-flow ecosystem works here.

Common situations: Users familiar with the 60+ agent types assuming templates are equally broad; shell tab-completion offering stale names; scripts parameterized with a task type that outgrew the three templates.

Related errors

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