ruvnet/ruflo · error · TypeError

selectAgentBackend: pod.preferLocalExecution must be boolean

Error message

selectAgentBackend: pod.preferLocalExecution must be boolean (validate via pod-schema first)

What it means

TypeError in selectAgentBackend() when pod.preferLocalExecution is present but not a boolean (e.g., a string "true", a number, or undefined). The field is the primary routing switch (true pins to local-stdio). A non-boolean value means the pod object was constructed or parsed without running validatePodTemplate(), which enforces the boolean type.

Source

Thrown at v3/@claude-flow/cli/src/business-pods/domain-affinity-policy.ts:56

export interface BackendDecision {
  backend: AgentBackend;
  reason: string;
}

/**
 * Decide which backend `@metaharness/router` should prefer for a pod tick.
 *
 * @param pod  A validated PodTemplate. Validation is the caller's
 *             responsibility; this function will throw on malformed input
 *             (specifically on missing `preferLocalExecution` or
 *             `budgetUsdMonthly`).
 */
export function selectAgentBackend(pod: PodTemplate): BackendDecision {
  if (pod === null || typeof pod !== 'object') {
    throw new TypeError('selectAgentBackend: pod must be a validated PodTemplate object');
  }
  if (typeof pod.preferLocalExecution !== 'boolean') {
    throw new TypeError(
      'selectAgentBackend: pod.preferLocalExecution must be boolean (validate via pod-schema first)',
    );
  }
  if (typeof pod.budgetUsdMonthly !== 'number' || !Number.isFinite(pod.budgetUsdMonthly)) {
    throw new TypeError(
      'selectAgentBackend: pod.budgetUsdMonthly must be a finite number (validate via pod-schema first)',
    );
  }

  if (pod.preferLocalExecution) {
    return {
      backend: 'local-stdio',
      reason: `pod "${pod.name}" preferLocalExecution=true — domain-affinity policy pins to local stdio`,
    };
  }
  if (pod.budgetUsdMonthly >= CLOUD_BUDGET_THRESHOLD_USD) {
    return {
      backend: 'cloud-managed',

View on GitHub (pinned to 6b01dc5a68)

Solutions

1. Run validatePodTemplate() on the pod — requireBoolean() enforces typeof === 'boolean' and throws PodTemplateValidationError with a clear path
2. If building the object in code, set preferLocalExecution to a literal true/false, never a string or number

Example fix

// before (YAML parsed preferLocalExecution as string "true"):
selectAgentBackend({ ...pod, preferLocalExecution: "true" }); // throws

// after:
const pod = validatePodTemplate(parsed);
selectAgentBackend(pod); // preferLocalExecution is now boolean true

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

// validatePodTemplate's requireBoolean() enforces typeof === 'boolean'
// for preferLocalExecution, so selectAgentBackend's boolean check is
// only a belt-and-suspenders guard.
const pod = validatePodTemplate(parsedJson);
selectAgentBackend(pod);

function hasValidPreferLocalExecution(pod: unknown): boolean {
  return typeof pod === 'object' && pod !== null
    && typeof (pod as { preferLocalExecution?: unknown }).preferLocalExecution === 'boolean';
}

When it happens

Trigger: Calling selectAgentBackend(pod) where pod is an object but pod.preferLocalExecution is a string ("true"/"false" from a YAML parser without boolean coercion), undefined, or a number.

Common situations: A YAML pod template with `preferLocalExecution: "true"` (quoted string); a hand-built PodTemplate object that omitted the field; a JSON source where the field was written as 1/0.

Related errors

• selectAgentBackend: pod must be a validated PodTemplate obje
• selectAgentBackend: pod.budgetUsdMonthly must be a finite nu
• pod-template at ${path}: field "${key}" must be a boolean
• pod-template at ${path}: field "${key}" must be a non-empty
• pod-template at ${path}: field "${key}" must be a finite num

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