ruvnet/ruflo · error · PodTemplateValidationError

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

Error message

pod-template at ${path}: field "${key}" must be a non-empty string

What it means

Thrown by the requireString() helper inside the pod-template schema validator. Fires when a required string field is missing (undefined), not the string type, or an empty string. The error carries the field name (key) and the JSON-pointer path so the caller can render a precise location. Used for top-level fields (name, displayName, roomId) and nested object fields (agent.role, bench.name, etc.).

Source

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

 * callers can render a precise message.
 */
export class PodTemplateValidationError extends Error {
  constructor(message: string, public path: string) {
    super(`pod-template at ${path}: ${message}`);
    this.name = 'PodTemplateValidationError';
  }
}

const PII_POLICIES: PiiPolicy[] = ['soc2', 'gdpr', 'hipaa', 'permissive'];

function isObject(v: unknown): v is Record<string, unknown> {
  return typeof v === 'object' && v !== null && !Array.isArray(v);
}

function requireString(parent: Record<string, unknown>, key: string, path: string): string {
  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;

View on GitHub (pinned to 6b01dc5a68)

Solutions

  1. Read the error's path and field name — they tell you exactly which JSON key to fix
  2. Cross-check against the PodTemplate interface in pod-schema.ts for the full list of required string fields
  3. Use the business_pod_validate MCP tool to validate before deploying a pod template

Example fix

// before:
{ "name": "sales", "displayname": "Sales Pod", ... } // typo: displayname
// throws: pod-template at /: field "displayName" must be a non-empty string

// after:
{ "name": "sales", "displayName": "Sales Pod", ... }
Defensive patterns

Strategy: validation

Validate before calling

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

try {
  const pod = validatePodTemplate(parsedJson);
  // pod is now a typed PodTemplate
} catch (e) {
  if (e instanceof PodTemplateValidationError) {
    console.error(`Invalid pod template at ${e.path}: ${e.message}`);
  }
}

Try / catch

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

try {
  const pod = validatePodTemplate(raw);
} catch (e) {
  if (e instanceof PodTemplateValidationError) {
    // e.path is the JSON pointer; e.message names the field
    console.error(`Validation failed: ${e.message}`);
    process.exit(1);
  }
  throw e;
}

Prevention

When it happens

Trigger: validatePodTemplate() encounters a field that requireString() is asked to read (name, displayName, roomId, piiPolicy, cronSchedule, agent.role, agent.agentType, agent.description, bench.name, bench.description) and that field is absent, non-string, or empty.

Common situations: A typo in the JSON key (e.g., "displayname" instead of "displayName" leaves displayName undefined); an empty string value; a value accidentally written as a number (roomId: 123); a truncated/copy-paste template missing a field.

Related errors

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