What causes "base_branch must be "main" (got "${spec.base_branch}")" in tinyhumansai/openhuman?

tinyhumansai/openhuman · error · SpecError

base_branch must be "main" (got "${spec.base_branch}")

Error message

base_branch must be "main" (got "${spec.base_branch}")

What it means

validateSpec() requires the top-level base_branch to be exactly "main"; any other branch name throws with the got-value shown. Batch agents are only ever cut from upstream/main per repo policy (the AGENTS.md rule "Never write code on main" work branches derive from main), so basing a batch on release/feature branches is rejected.

Source

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

  }
  for (const key of REQUIRED_TOP) {
    if (!(key in spec))
      throw new SpecError(`missing required top-level field "${key}"`);
  }
  if (
    typeof spec.batch_id !== "string" ||
    !/^[a-z0-9][a-z0-9-]*$/.test(spec.batch_id)
  ) {
    throw new SpecError("batch_id must be a kebab-case slug", "batch_id");
  }
  if (spec.base_repo !== "tinyhumansai/openhuman") {
    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",
    );

View on GitHub (pinned to a221052e0d)

Solutions

Change base_branch to "main"
If the work must target release, note the batch tooling does not support it — run the batch off main and let the normal promote-main-to-release flow carry it
Remove the field only if you also want the earlier REQUIRED_TOP "missing required top-level field" error instead — it is mandatory

Example fix

// before
"base_branch": "master"

// after
"base_branch": "main"

Defensive patterns

Strategy: validation

Validate before calling

if (spec.base_branch !== "main") {
  console.error(`base_branch must be main, got ${spec.base_branch}`);
  process.exit(1);
}

Type guard

/** @param {unknown} v */
function isMainBranch(v) {
  return v === "main";
}

Try / catch

try {
  validateSpec(spec);
} catch (e) {
  if (e instanceof SpecError && e.path === "base_branch") {
    console.error(`fix ${specPath}: ${e.message}`);
    process.exit(1);
  }
  throw e;
}

Prevention

Remember the batch tooling only supports main — do not try to adapt specs from release-targeting workflows
Pin base_branch in the template so editors cannot change it accidentally

When it happens

Trigger: A spec with "base_branch": "master", "release", "develop", or a PR branch name like "feat/batch-august" passed to validateSpec or the agent-batch CLI entry points.

Common situations: Porting a spec from an older repo default of "master"; attempting to replay a batch against the long-lived release branch; copy-pasting from a workflow that targets release.

Related errors

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