coleam00/Archon · error · IncludeExpansionError

include target '${name}' not found

Error message

include target '${name}' not found

What it means

Raised as `IncludeExpansionError` when the include expander is asked to expand a workflow name that has no entry in `rawByName`. Top-level names always exist (they come from rawByName keys), so this only fires when a workflow was reached as an include TARGET that does not exist anywhere in the loaded set — i.e. a dangling include reference.

Source

Thrown at packages/workflows/src/include-expander.ts:1237

    // Cycle + depth are checked BEFORE the memo so a node memoized via a shallow path
    // can never mask a too-deep or cyclic reference reaching it via a longer path.
    if (stack.includes(name)) {
      throw new IncludeExpansionError(`include cycle detected: ${[...stack, name].join(' -> ')}`);
    }
    if (stack.length > INCLUDE_MAX_DEPTH) {
      throw new IncludeExpansionError(
        `include depth limit exceeded (max ${String(INCLUDE_MAX_DEPTH)} levels): ${[...stack, name].join(' -> ')}`
      );
    }

    const cached = memo.get(name);
    if (cached) return cached;

    const raw = rawByName.get(name);
    if (!raw) {
      // Top-level names always exist (they come from rawByName.keys()); this only
      // fires when the name was reached as an unresolvable include TARGET.
      throw new IncludeExpansionError(`include target '${name}' not found`);
    }

    // Collapse this workflow's own node-affecting scope onto its own nodes BEFORE
    // anything is inlined, so each node carries what its AUTHOR declared and the
    // workflow-level layer is gone by the time a parent's could reach it. This replaces
    // the old byte-for-byte fast path for include-free workflows — every workflow is
    // cloned now, deliberately: the alternative is a workflow that behaves differently
    // depending on whether it happens to contain an `include:`.
    const collapsed = collapseWorkflowScope(raw);
    // Capability requirements union UPWARD (#1764): a composed workflow's `requires:` is
    // a fact about what its nodes need, not a choice the composing run makes. Dropping it
    // turned a clean pre-cost refusal into a mid-run failure inside a block the parent
    // cannot inspect. A union can only make a run refuse EARLIER.
    const expanded = expandNodeList(collapsed.nodes, name, stack);
    const requires: WorkflowRequirement[] = [
      ...(collapsed.requires ?? []),
      ...expanded.includedRequirements,
    ];

View on GitHub (pinned to 0773b97458)

Solutions

1. Check the include target name for typos against the set of loaded workflow names
2. Ensure the include-target file exists and is passed to `expandWorkflowIncludes` (it only expands what was loaded)
3. If the target was intentionally removed, remove the include reference from the parent workflow
4. Confirm no loader filter (allowlist, ignore rules) is excluding the target file

Example fix

# before
includes:
  - deploy-pipline   # typo
# after
includes:
  - deploy-pipeline

// Validate all include targets exist before expansion.
function validateIncludes(raws: Map<string, unknown>): string[] {
  const missing: string[] = [];
  for (const raw of raws.values()) {
    for (const inc of (raw as { includes?: string[] }).includes ?? []) {
      if (!raws.has(inc)) missing.push(inc);
    }
  }
  return missing; // empty array means all targets resolve
}

try {
  const expanded = expandWorkflowIncludes(rawByName);
} catch (err) {
  if (err instanceof IncludeExpansionError && /include target '.*' not found/.test(err.message)) {
    throw new Error(`Fix the include reference: ${err.message}`, { cause: err });
  }
  throw err;
}

When it happens

Trigger: A workflow's `includes:` (or equivalent include field) names a workflow that was never loaded into `rawByName` — misspelled include target, target file not passed to the expander, or the target was filtered out before expansion.

Common situations: Renaming or deleting a workflow file that other workflows include, typos in include names, packaging workflows in separate directories where the include target was never registered with the expander.

Related errors

• structureError (DAG structure validation message, wrapped in
• outcomeDeclarationError (workflow outcome declaration valida
• ${label}: unknown key '${key}' will be ignored.${hint}
• Invalid --status '${opts.status}'. Valid: ${workflowRunStatu
• Invalid run config at 'document': expected an object

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