What causes "Dry-run stub file not found: ${path}" in coleam00/Archon?

Verify the path exists (ls the file) and run the command from the directory containing it, or pass an absolute path.

coleam00/Archon · error · Error

Dry-run stub file not found: ${path}

Error message

Dry-run stub file not found: ${path}

What it means

Thrown by loadDryRunStubs when a stub file path is supplied but Bun's file.exists() reports the file is missing. The loader requires an explicit, existing file; it does not silently return empty stubs for a bad path.

Source

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

  missingStubs: z.array(z.string()),
  /**
   * The subset of `missingStubs` a `trigger_rule: all_done` join tolerated (#2869) —
   * hydrated with a generated placeholder rather than failing the node. Always a
   * subset of `missingStubs`, never a replacement for it: a consumer that only cares
   * about genuinely blocking gaps filters `missingStubs` by this list; one that wants
   * every unverified node (the pre-#2869 contract) keeps reading `missingStubs` alone.
   */
  toleratedMissingStubs: z.array(z.string()),
  unusedStubs: z.array(z.string()),
  summary: z.string().optional(),
});
export type DryRunResult = z.infer<typeof dryRunResultSchema>;

export async function loadDryRunStubs(path?: string): Promise<DryRunStubs> {
  if (!path) return {};
  const file = Bun.file(path);
  if (!(await file.exists())) {
    throw new Error(`Dry-run stub file not found: ${path}`);
  }

  let parsed: unknown;
  try {
    parsed = Bun.YAML.parse(await file.text());
  } catch (error) {
    throw new Error(`Failed to parse dry-run stub file '${path}': ${(error as Error).message}`);
  }

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

View on GitHub (pinned to 0773b97458)

Solutions

Verify the path exists (ls the file) and run the command from the directory containing it, or pass an absolute path.
Generate the stub file first via the dry-run scaffold if it was never created.
Omit the stub path argument if no stubs are needed (loader returns {}).

Example fix

// before
const stubs = await loadDryRunStubs("./stubs.yaml"); // CWD is elsewhere
// after
const stubs = await loadDryRunStubs("/abs/path/to/stubs.yaml");

Defensive patterns

Strategy: validation

Validate before calling

import { existsSync } from "node:fs";
import { resolve } from "node:path";
function stubFileReady(path?: string): boolean {
  if (!path) return true;
  return existsSync(resolve(process.cwd(), path));
}

Type guard

null

Try / catch

try {
  const stubs = await loadDryRunStubs(path);
} catch (err) {
  if (err instanceof Error && err.message.startsWith("Dry-run stub file not found")) {
    console.warn(`No stub file at ${path}; continuing with empty stubs.`);
    return {};
  }
  throw err;
}

Prevention

Pass absolute paths or resolve relative to a known base directory.
Run the scaffold step before any stub-consuming command.
Check file existence in shell scripts before invoking the loader.
Don't clean up stub files mid-pipeline.

When it happens

Trigger: Calling loadDryRunStubs(path) — directly or via stubs/result/loaded entry points — where `path` points to a nonexistent or deleted file, or a typo'd/relative path resolved from the wrong working directory.

Common situations: Passing `--stubs stubs.yaml` from a different working directory, forgetting to run the scaffold step first, deleting the stub during cleanup scripts, or a renamed stub file.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

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