coleam00/Archon · error · Error

Invalid dry-run stub file '${path}': ${issues}

Error message

Invalid dry-run stub file '${path}': ${issues}

What it means

Thrown by loadDryRunStubs when dryRunStubsSchema.safeParse rejects the parsed YAML. The file is a mapping and passes the reserved-key check, but values violate the stub schema; all zod issues are joined as `<path>: <message>` for a single-shot diagnosis.

Source

Thrown at packages/workflows/src/dry-run.ts:414

  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
    throw new Error(
      `Invalid dry-run stub file '${path}': expected one YAML mapping of node ids to outputs`
    );
  }
  const reservedHit = Object.keys(parsed as Record<string, unknown>).find(key =>
    RESERVED_FIXTURE_KEYS.has(key)
  );
  if (reservedHit !== undefined) {
    throw new Error(
      `Invalid dry-run stub file '${path}': contains the fixture key '${reservedHit}' — this is a fixture file; run it with 'workflow test'`
    );
  }
  const result = dryRunStubsSchema.safeParse(parsed);
  if (!result.success) {
    const issues = result.error.issues
      .map(issue => `${issue.path.join('.') || '<root>'}: ${issue.message}`)
      .join('; ');
    throw new Error(`Invalid dry-run stub file '${path}': ${issues}`);
  }
  return result.data;
}

function nodeType(node: DagNode): z.infer<typeof dryRunNodeTypeSchema> {
  // `include:` is no longer a DagNode member (#2486) — it never reaches this function.
  if (isAgentNode(node) && node.source.kind === 'command') return 'command';
  if (isExecNode(node)) return node.runtime === 'sh' ? 'bash' : 'script';
  if (isLoopNode(node)) return 'loop';
  if (isLoopGroupNode(node)) return 'loop_group';
  if (isGateNode(node)) return 'approval';
  if (isWaitNode(node)) return 'wait';
  if (isHaltNode(node)) return 'cancel';
  if (isWorkflowNode(node)) return 'workflow';
  if (isComposeFanOutNode(node)) return 'compose_fan_out';
  return 'prompt';
}

View on GitHub (pinned to 0773b97458)

Solutions

  1. Read each `path: message` issue and correct the offending stub value's type/shape.
  2. Regenerate the stub scaffold so values match the current node output_format shapes.
  3. Check whether the workflow's output_format changed since the stub was written and update the stub accordingly.

Example fix

# before (score must be number)
summarize:
  score: "high"
# after
summarize:
  score: 0.9
Defensive patterns

Strategy: validation

Validate before calling

function stubValueMatchesOutputFormat(node: { id: string; output_format?: object }, stubs: Record<string, unknown>): string[] {
  const issues: string[] = [];
  for (const [id, value] of Object.entries(stubs)) {
    const schema = nodes.find(n => n.id === id)?.output_format;
    if (schema && typeof value !== "object") issues.push(`${id}: expected object output`);
  }
  return issues;
}

Type guard

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

Try / catch

try {
  const stubs = await loadDryRunStubs(path);
} catch (err) {
  if (err instanceof Error && err.message.startsWith("Invalid dry-run stub file") && err.message.includes(":")) {
    for (const issue of err.message.split("Invalid dry-run stub file")[1].split("; ")) {
      console.error(`stub issue: ${issue.trim()}`);
    }
  } else throw err;
}

Prevention

When it happens

Trigger: Loading a stub file whose per-node output values have the wrong shape — e.g. a node id mapped to a scalar where an object is required, wrong-typed fields inside the output, or a `<root>` issue when the top-level shape itself is wrong.

Common situations: Hand-writing stub values that don't match the node's declared output shape, renaming output fields after editing a workflow, or older stub files predating a stub-schema change.

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

AI-assisted analysis of coleam00/Archon@0773b97458 (2026-09-01). Data as JSON: /api/errors/bd17f75251fe3c15. Report an issue: GitHub.