coleam00/Archon · error · Error

${result.message}

Error message

${result.message}

What it means

During a dry-run simulation, when a workflow node loads a command prompt, `loadDryRunCommand` calls `loadCommandPrompt` and propagates any failure by throwing a plain Error carrying the loader's message. The library throws this because a dry run must resolve the exact command text the real run would use; if the command cannot be loaded from the dry-run source roots, simulation cannot proceed honestly.

Source

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

async function loadDryRunCommand(ctx: DryRunContext, command: string): Promise<string> {
  const result = await loadCommandPrompt(
    {
      // Unreachable: `loadCommandPrompt` consults `loadConfig` only when its source roots
      // carry no `load_default_commands`, and `ctx.sourceRoots` always does — the field is
      // a required boolean on every roots value. Throwing rather than returning a stub
      // config keeps a future signature change from silently resolving commands against a
      // fabricated policy.
      loadConfig: () => {
        throw new Error('dry-run resolves commands from its source roots, never from config');
      },
    },
    ctx.cwd,
    command,
    undefined,
    ctx.sourceRoots
  );
  if (!result.success) throw new Error(result.message);
  return result.content;
}

function resolveText(
  text: string,
  ctx: DryRunContext,
  outputs: Map<string, NodeOutput>,
  shellSafe = false,
  loopPrevOutput = '',
  escapeNodeOutputs = shellSafe,
  // The `$INPUTS` bag for this text — run-level inputs unless the node carries
  // node-local `with:` bindings, which merge OVER them (#2637; nearest wins,
  // matching the executor's command-prompt path).
  inputs: Record<string, JsonValue> | undefined = ctx.inputs
): string {
  const docsDir = join(ctx.cwd, 'docs');
  const substituted = substituteWorkflowVariables(
    text,

View on GitHub (pinned to 0773b97458)

Solutions

  1. Verify the command file exists at the path the node references, within the source roots passed to the dry run
  2. Fix syntax/frontmatter errors in the command file (run the loader or a YAML parser on it)
  3. Check that ctx.sourceRoots points at the correct repository root and includes the commands directory
  4. Run the same command load in a real (non-dry) run to compare the resolved source roots

Example fix

// before: command referenced by a node does not exist
command: deploy-steps   // no commands/deploy-steps.md in source roots
// after
command: deploy-steps   // commands/deploy-steps.md present in repo
Defensive patterns

Strategy: try-catch

Validate before calling

import { existsSync, statSync } from 'node:fs';
import { join } from 'node:path';
// Verify the command file resolves inside one of the source roots before dry-running.
function commandFileExists(command: string, sourceRoots: string[]): boolean {
  return sourceRoots.some((root) => {
    for (const rel of [`commands/${command}.md`, `${command}.md`]) {
      const p = join(root, rel);
      if (existsSync(p) && statSync(p).isFile()) return true;
    }
    return false;
  });
}

Try / catch

try {
  const content = await loadDryRunCommand(ctx, command);
} catch (err) {
  // loadDryRunCommand throws the loader's message verbatim; rethrow with the command name for context.
  throw new Error(`dry-run: cannot load command '${command}': ${(err as Error).message}`, { cause: err });
}

Prevention

When it happens

Trigger: Calling `loadDryRunCommand(ctx, command)` (via simulateLoop/sourceText) when `loadCommandPrompt` returns `{success: false}` — typically because the referenced command file is missing from `ctx.sourceRoots`, unreadable, or fails frontmatter/parse validation. Note the dry-run path never falls back to `loadConfig`; commands resolve only from the provided source roots.

Common situations: Running `archon dry-run` against a repo whose `commands/` directory was renamed or moved, a typo in a node's `command:` reference, a command file present only in a config dir that dry-run intentionally ignores, or a YAML syntax error inside the command file.

Related errors

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