{"record":{"id":"977b9ed65f7d678f","repo":"ruvnet/ruflo","slug":"pod-template-at-path-field-key-must-be-an","errorCode":null,"errorMessage":"pod-template at ${path}: field \"${key}\" must be an array","messagePattern":"pod-template at (.+?): field \"(.+?)\" must be an array","errorType":"validation","errorClass":"PodTemplateValidationError","httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/cli/src/business-pods/pod-schema.ts","lineNumber":121,"sourceCode":"  if (typeof v !== 'number' || !Number.isFinite(v)) {\n    throw new PodTemplateValidationError(`field \"${key}\" must be a finite number`, path);\n  }\n  return v;\n}\n\nfunction requireBoolean(parent: Record<string, unknown>, key: string, path: string): boolean {\n  const v = parent[key];\n  if (typeof v !== 'boolean') {\n    throw new PodTemplateValidationError(`field \"${key}\" must be a boolean`, path);\n  }\n  return v;\n}\n\nfunction requireArray<T>(parent: Record<string, unknown>, key: string, path: string,\n                          itemValidator: (item: unknown, ipath: string) => T): T[] {\n  const v = parent[key];\n  if (!Array.isArray(v)) {\n    throw new PodTemplateValidationError(`field \"${key}\" must be an array`, path);\n  }\n  return v.map((item, idx) => itemValidator(item, `${path}/${key}[${idx}]`));\n}\n\nfunction validatePodAgent(item: unknown, path: string): PodAgent {\n  if (!isObject(item)) throw new PodTemplateValidationError('agent must be an object', path);\n  return {\n    role: requireString(item, 'role', path),\n    agentType: requireString(item, 'agentType', path),\n    description: requireString(item, 'description', path),\n    preferLocal: requireBoolean(item, 'preferLocal', path),\n  };\n}\n\nfunction validatePodBench(item: unknown, path: string): PodBench {\n  if (!isObject(item)) throw new PodTemplateValidationError('bench must be an object', path);\n  const name = requireString(item, 'name', path);\n  const description = requireString(item, 'description', path);","sourceCodeStart":103,"sourceCodeEnd":139,"githubUrl":"https://github.com/ruvnet/ruflo/blob/6b01dc5a687b26b3e218f796de45ec51f8fa9e8c/v3/@claude-flow/cli/src/business-pods/pod-schema.ts#L103-L139","documentation":"Thrown by the requireArray() helper inside the pod-template schema validator. Fires when a field expected to be an array is instead a non-array value (object, string, number, null, undefined). Used for agents, allowedMcpTools (top-level), bench.successCriteria, and auditReadView.includedEventTypes.","triggerScenarios":"validatePodTemplate() encounters a field that requireArray() reads and the value is not recognized by Array.isArray() — e.g., a single object instead of a list, a comma-separated string, or a missing field (undefined).","commonSituations":"A single agent written as an object instead of wrapped in an array; allowedMcpTools written as a comma-separated string; a missing array field; a value accidentally set to null.","solutions":["Read the error path and field name to find which field should be an array","Wrap single items in square brackets, and ensure list fields are JSON arrays","For allowedMcpTools and agents, provide at least one entry (empty arrays are rejected by separate downstream checks)"],"exampleFix":"// before:\n\"agents\": { \"role\": \"lead\", ... } // object, throws\n\n// after:\n\"agents\": [ { \"role\": \"lead\", ... } ] // array","handlingStrategy":"validation","validationCode":"import { validatePodTemplate, PodTemplateValidationError } from '@claude-flow/cli/business-pods/pod-schema';\n\ntry {\n  const pod = validatePodTemplate(parsedJson);\n} catch (e) {\n  if (e instanceof PodTemplateValidationError) {\n    console.error(`Array field error at ${e.path}: ${e.message}`);\n  }\n}","typeGuard":null,"tryCatchPattern":"import { validatePodTemplate, PodTemplateValidationError } from '@claude-flow/cli/business-pods/pod-schema';\n\ntry {\n  const pod = validatePodTemplate(raw);\n} catch (e) {\n  if (e instanceof PodTemplateValidationError) {\n    console.error(e.message);\n    process.exit(1);\n  }\n  throw e;\n}","preventionTips":["Ensure list fields (agents, allowedMcpTools, successCriteria, includedEventTypes) are JSON arrays, not single objects or comma-separated strings","Validate templates with validatePodTemplate() in CI","Wrap single items in square brackets"],"tags":["validation","pod-template","schema","arrays"],"backgroundTag":null,"analyzedSha":"6b01dc5a687b26b3e218f796de45ec51f8fa9e8c","analyzedAt":"2026-08-12T13:20:50.148Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}