ruvnet/ruflo · error · PodTemplateValidationError

field "${key}" must be a non-empty string

Error message

field "${key}" must be a non-empty string

What it means

Pod template validator's requireString() throws PodTemplateValidationError when a required string field is missing, not a string, or an empty string. The error carries the JSON pointer path (rendered as 'pod-template at <path>: ...') so you can locate the offending key inside plugins/ruflo-business-pods/templates/*.json.

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 fa13ee4ad6)

Solutions

1. Read the path in the error: it names the exact field and its location — add/fix that key in the template JSON
2. Cross-check against the PodTemplate interface in pod-schema.ts for the full required-field list
3. Validate templates in CI before shipping: run the validator as a lint step so typos never deploy
4. Don't rely on TypeScript — templates are runtime JSON, so runtime validation is the only gate

Example fix

// before
{ "name": "sales", "roomId": "sales", "displayName": "" }
// after
{ "name": "sales", "roomId": "sales", "displayName": "Sales Pipeline Pod" }

// Pre-flight a template before registering it
try {
  validatePodTemplate(JSON.parse(fs.readFileSync(tplPath, 'utf8')));
} catch (e) {
  if (e instanceof PodTemplateValidationError) fail(`${tplPath}: ${e.message}`);
  throw e;
}

function hasNonEmptyString(o: Record<string, unknown>, key: string): boolean {
  return typeof o[key] === 'string' && (o[key] as string).length > 0;
}

try {
  validatePodTemplate(template);
} catch (e) {
  if (e instanceof PodTemplateValidationError) {
    // e.path is a JSON pointer to the exact offending field
    reportTemplateIssue(e.path, e.message);
  } else throw e;
}

When it happens

Trigger: validatePodTemplate() on a template where any required string field (name, displayName, roomId, agents[].role/agentType/description, bench.name/description, cronSchedule, ...) is absent, null, a number, or "". The failing key name is interpolated into the message.

Common situations: Hand-edited pod template JSON with a typo'd key (displayname vs displayName); template copied from docs that omitted optional-looking fields; agents entries reduced to plain strings instead of objects; trailing whitespace-only values are NOT caught (only empty), but outright missing keys are.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• field "${key}" must be a finite number
• field "${key}" must be a boolean
• field "${key}" must be an array
• agent must be an object
• bench must be an object

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