{"record":{"id":"beb39e91d97fa988","repo":"coleam00/Archon","slug":"include-target-name-not-found","errorCode":null,"errorMessage":"include target '${name}' not found","messagePattern":"include target '(.+?)' not found","errorType":"exception","errorClass":"IncludeExpansionError","httpStatus":null,"severity":"error","filePath":"packages/workflows/src/include-expander.ts","lineNumber":1237,"sourceCode":"    // Cycle + depth are checked BEFORE the memo so a node memoized via a shallow path\n    // can never mask a too-deep or cyclic reference reaching it via a longer path.\n    if (stack.includes(name)) {\n      throw new IncludeExpansionError(`include cycle detected: ${[...stack, name].join(' -> ')}`);\n    }\n    if (stack.length > INCLUDE_MAX_DEPTH) {\n      throw new IncludeExpansionError(\n        `include depth limit exceeded (max ${String(INCLUDE_MAX_DEPTH)} levels): ${[...stack, name].join(' -> ')}`\n      );\n    }\n\n    const cached = memo.get(name);\n    if (cached) return cached;\n\n    const raw = rawByName.get(name);\n    if (!raw) {\n      // Top-level names always exist (they come from rawByName.keys()); this only\n      // fires when the name was reached as an unresolvable include TARGET.\n      throw new IncludeExpansionError(`include target '${name}' not found`);\n    }\n\n    // Collapse this workflow's own node-affecting scope onto its own nodes BEFORE\n    // anything is inlined, so each node carries what its AUTHOR declared and the\n    // workflow-level layer is gone by the time a parent's could reach it. This replaces\n    // the old byte-for-byte fast path for include-free workflows — every workflow is\n    // cloned now, deliberately: the alternative is a workflow that behaves differently\n    // depending on whether it happens to contain an `include:`.\n    const collapsed = collapseWorkflowScope(raw);\n    // Capability requirements union UPWARD (#1764): a composed workflow's `requires:` is\n    // a fact about what its nodes need, not a choice the composing run makes. Dropping it\n    // turned a clean pre-cost refusal into a mid-run failure inside a block the parent\n    // cannot inspect. A union can only make a run refuse EARLIER.\n    const expanded = expandNodeList(collapsed.nodes, name, stack);\n    const requires: WorkflowRequirement[] = [\n      ...(collapsed.requires ?? []),\n      ...expanded.includedRequirements,\n    ];","sourceCodeStart":1219,"sourceCodeEnd":1255,"githubUrl":"https://github.com/coleam00/Archon/blob/0773b9745896ef0612e709c80845a0f7db315b19/packages/workflows/src/include-expander.ts#L1219-L1255","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the include target name for typos against the set of loaded workflow names","Ensure the include-target file exists and is passed to `expandWorkflowIncludes` (it only expands what was loaded)","If the target was intentionally removed, remove the include reference from the parent workflow","Confirm no loader filter (allowlist, ignore rules) is excluding the target file"],"exampleFix":"# before\nincludes:\n  - deploy-pipline   # typo\n# after\nincludes:\n  - deploy-pipeline","handlingStrategy":"validation","validationCode":"// Validate all include targets exist before expansion.\nfunction validateIncludes(raws: Map<string, unknown>): string[] {\n  const missing: string[] = [];\n  for (const raw of raws.values()) {\n    for (const inc of (raw as { includes?: string[] }).includes ?? []) {\n      if (!raws.has(inc)) missing.push(inc);\n    }\n  }\n  return missing; // empty array means all targets resolve\n}","typeGuard":null,"tryCatchPattern":"try {\n  const expanded = expandWorkflowIncludes(rawByName);\n} catch (err) {\n  if (err instanceof IncludeExpansionError && /include target '.*' not found/.test(err.message)) {\n    throw new Error(`Fix the include reference: ${err.message}`, { cause: err });\n  }\n  throw err;\n}","preventionTips":["Grep workflow includes: names against actual workflow filenames before committing","Never delete or rename a workflow file without grepping for its name in includes:","Pass every workflow file in the tree to the expander, not a filtered subset","Add a CI check that expands all workflows as a smoke test"],"tags":["workflow","includes","config","validation"],"backgroundTag":"include-target-not-found","analyzedSha":"0773b9745896ef0612e709c80845a0f7db315b19","analyzedAt":"2026-09-01T02:28:07.064Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}