What causes "Dry-run stub scaffold already exists: ${path}" in coleam00/Archon?

Delete the existing scaffold file at `path` (or point to a new path) and re-run.

coleam00/Archon · error · Error

EEXIST

EEXIST

Error message

Dry-run stub scaffold already exists: ${path}

What it means

Thrown by writeDryRunStubScaffold when opening the scaffold file with the exclusive 'wx' flag fails with EEXIST, meaning a file already exists at the target path. The scaffolder never overwrites an existing stub scaffold, so it raises a descriptive error instead of the raw EEXIST.

Source

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

    })
  );
}

/** Write a scaffold without ever overwriting an existing fixture. */
export async function writeDryRunStubScaffold(
  workflow: WorkflowDefinition,
  path: string
): Promise<DryRunStubs> {
  const stubs = createDryRunStubScaffold(workflow);
  await mkdir(dirname(path), { recursive: true });
  let handle;
  try {
    handle = await open(path, 'wx');
    await handle.writeFile(Bun.YAML.stringify(stubs));
  } catch (error) {
    const err = error as NodeJS.ErrnoException;
    if (err.code === 'EEXIST') {
      throw new Error(`Dry-run stub scaffold already exists: ${path}`);
    }
    throw error;
  } finally {
    await handle?.close();
  }
  return stubs;
}

const dryRunNodeTypeSchema = z.enum([
  'command',
  'prompt',
  'bash',
  'script',
  'loop',
  'loop_group',
  'approval',
  'wait',
  'cancel',

View on GitHub (pinned to 0773b97458)

Solutions

Delete the existing scaffold file at `path` (or point to a new path) and re-run.
Edit the existing stub file in place instead of regenerating it.
In scripts, remove the stale file first (rm the recorded path) before scaffolding.

Example fix

// before
await writeDryRunStubScaffold(dag, "stubs.yaml"); // EEXIST on second run
// after
await fs.rm("stubs.yaml", { force: true });
await writeDryRunStubScaffold(dag, "stubs.yaml");

Defensive patterns

Strategy: try-catch

Validate before calling

import { existsSync } from "node:fs";
function scaffoldPathIsFree(path: string): boolean {
  return !existsSync(path);
}

Type guard

null

Try / catch

try {
  await writeDryRunStubScaffold(dag, path);
} catch (err) {
  if (err instanceof Error && err.message.startsWith("Dry-run stub scaffold already exists")) {
    console.warn(`Reusing existing scaffold at ${path}`);
    return await loadDryRunStubs(path);
  }
  throw err;
}

Prevention

Delete or version the scaffold path before regenerating (timestamped filenames help).
Load the existing scaffold and edit it instead of re-scaffolding.
Clean up scaffold files in script teardown.
Use per-run output directories so reruns never collide.

When it happens

Trigger: Calling writeDryRunStubScaffold (via scaffold/written entry points) with a `path` where a stub file was already written by a previous dry-run scaffold invocation.

Common situations: Re-running scaffold generation without deleting the previous stub file, scripting that reuses the same output path, or a crashed earlier run that left the scaffold behind.

Understand the failure class

Background: "already exists" / EEXIST / FileAlreadyExistsException: what the 'file already exists' error means and how to fix it — this error's family across 37 libraries.

Related errors

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