ruvnet/ruflo · error · PodTemplateValidationError

pod-template at ${path}: field "${key}" must be a boolean

Error message

pod-template at ${path}: field "${key}" must be a boolean

What it means

Thrown by the requireBoolean() helper inside the pod-template schema validator. Fires when a required boolean field is present but not the boolean type (e.g., the string "true", a number 1, or undefined). Used for preferLocalExecution (top-level) and preferLocal (per-agent).

Source

Thrown at v3/@claude-flow/cli/src/business-pods/pod-schema.ts:112

  const v = parent[key];
  if (typeof v !== 'string' || v.length === 0) {
    throw new PodTemplateValidationError(`field "${key}" must be a non-empty string`, path);
  }
  return v;
}

function requireNumber(parent: Record<string, unknown>, key: string, path: string): number {
  const v = parent[key];
  if (typeof v !== 'number' || !Number.isFinite(v)) {
    throw new PodTemplateValidationError(`field "${key}" must be a finite number`, path);
  }
  return v;
}

function requireBoolean(parent: Record<string, unknown>, key: string, path: string): boolean {
  const v = parent[key];
  if (typeof v !== 'boolean') {
    throw new PodTemplateValidationError(`field "${key}" must be a boolean`, path);
  }
  return v;
}

function requireArray<T>(parent: Record<string, unknown>, key: string, path: string,
                          itemValidator: (item: unknown, ipath: string) => T): T[] {
  const v = parent[key];
  if (!Array.isArray(v)) {
    throw new PodTemplateValidationError(`field "${key}" must be an array`, path);
  }
  return v.map((item, idx) => itemValidator(item, `${path}/${key}[${idx}]`));
}

function validatePodAgent(item: unknown, path: string): PodAgent {
  if (!isObject(item)) throw new PodTemplateValidationError('agent must be an object', path);
  return {
    role: requireString(item, 'role', path),
    agentType: requireString(item, 'agentType', path),

View on GitHub (pinned to 6b01dc5a68)

Solutions

1. Read the error path to find which boolean field is malformed (top-level preferLocalExecution or a nested agent.preferLocal)
2. Use literal true/false in YAML and JSON — avoid quotes around boolean values
3. If using a YAML parser, ensure it applies YAML 1.1 boolean coercion or pre-coerce the values

Example fix

// before (YAML):
preferLocalExecution: "true"  # string, throws

// after:
preferLocalExecution: true   # boolean

import { validatePodTemplate, PodTemplateValidationError } from '@claude-flow/cli/business-pods/pod-schema';

try {
  const pod = validatePodTemplate(parsedJson);
} catch (e) {
  if (e instanceof PodTemplateValidationError) {
    console.error(`Boolean field error at ${e.path}: ${e.message}`);
  }
}

import { validatePodTemplate, PodTemplateValidationError } from '@claude-flow/cli/business-pods/pod-schema';

try {
  const pod = validatePodTemplate(raw);
} catch (e) {
  if (e instanceof PodTemplateValidationError) {
    console.error(e.message);
    process.exit(1);
  }
  throw e;
}

When it happens

Trigger: validatePodTemplate() encounters preferLocalExecution or an agent's preferLocal whose value is a string, number, undefined, or null.

Common situations: YAML parsers producing quoted strings ("true") instead of booleans; a template authored with 1/0 integer flags; a field accidentally omitted from a hand-written template.

Related errors

• selectAgentBackend: pod.preferLocalExecution must be boolean
• pod-template at ${path}: field "${key}" must be a non-empty
• pod-template at ${path}: field "${key}" must be a finite num
• pod-template at ${path}: field "${key}" must be an array
• pod-template at ${path}: agent must be an object

AI-assisted analysis of ruvnet/ruflo@6b01dc5a68 (2026-08-12). Data as JSON: /api/errors/28f2619acc9773ca. Report an issue: GitHub.