What causes "agents must be a non-empty array" in tinyhumansai/openhuman?

Add at least one valid agent object {id, issue, title, branch, owned_paths}

tinyhumansai/openhuman · error · SpecError

agents must be a non-empty array

Error message

agents must be a non-empty array

What it means

The top-level agents field must be a non-empty Array — the batch must contain at least one agent entry to be meaningful. This fires before any per-agent validation, so an empty or malformed agents list is reported before confusing downstream errors. The path tag is "agents".

Source

Thrown at scripts/agent-batch/lib.mjs:75

    throw new SpecError(
      `base_repo must be "tinyhumansai/openhuman" (got "${spec.base_repo}")`,
      "base_repo",
    );
  }
  if (spec.base_branch !== "main") {
    throw new SpecError(
      `base_branch must be "main" (got "${spec.base_branch}")`,
      "base_branch",
    );
  }
  if (!Number.isInteger(spec.tracking_issue) || spec.tracking_issue <= 0) {
    throw new SpecError(
      "tracking_issue must be a positive integer",
      "tracking_issue",
    );
  }
  if (!Array.isArray(spec.agents) || spec.agents.length === 0) {
    throw new SpecError("agents must be a non-empty array", "agents");
  }
  if (spec.agents.length > 25) {
    throw new SpecError(
      `batch size ${spec.agents.length} exceeds hard cap of 25`,
      "agents",
    );
  }

  const seenId = new Set();
  const seenIssue = new Set();
  const seenBranch = new Set();
  for (let i = 0; i < spec.agents.length; i++) {
    const agent = spec.agents[i];
    const at = `agents[${i}]`;
    if (!agent || typeof agent !== "object" || Array.isArray(agent)) {
      throw new SpecError("must be an object", at);
    }
    for (const key of REQUIRED_AGENT) {

View on GitHub (pinned to a221052e0d)

Solutions

Add at least one valid agent object {id, issue, title, branch, owned_paths}
Ensure agents is a JSON array, not an object map
If you meant to validate a spec skeleton, finish populating it first — validateSpec has no draft mode

Example fix

// before
"agents": []

// after
"agents": [
  { "id": "a01", "issue": 5312, "title": "Fix CI timeout", "branch": "cursor/a01-5312-fix-ci-timeout", "owned_paths": ["scripts/ci/"] }
]

Defensive patterns

Strategy: validation

Validate before calling

if (!Array.isArray(spec.agents) || spec.agents.length === 0) {
  console.error("agents must be a non-empty array");
  process.exit(1);
}

Type guard

/** @param {unknown} v */
function isNonEmptyArray(v) {
  return Array.isArray(v) && v.length > 0;
}

Try / catch

try {
  validateSpec(spec);
} catch (e) {
  if (e instanceof SpecError && e.path === "agents") {
    console.error(e.message);
    process.exit(1);
  }
  throw e;
}

Prevention

Validate the skeleton early in authoring, not just before launch
When generating agents from a work list, assert the list is non-empty before emitting the spec

When it happens

Trigger: "agents": [], "agents": {} (object, not array), "agents": null, or agents omitted-but-null after the REQUIRED_TOP check passed with the key present holding a non-array.

Common situations: Starting a spec from a skeleton where agents was left empty to fill in later; a generator bug emitting an object keyed by agent id instead of an array; JSON merge tools dropping array contents.

Related errors

AI-assisted analysis of tinyhumansai/openhuman@a221052e0d (2026-08-16). Data as JSON: /api/errors/479a8909ffb04a90. Report an issue: GitHub.