{"record":{"id":"80c40a7d06d2c519","repo":"gastownhall/beads","slug":"inline-expand-on-step-q-loading-q-w","errorCode":null,"errorMessage":"inline expand on step %q: loading %q: %w","messagePattern":"inline expand on step %q: loading %q: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/formula/expand.go","lineNumber":472,"sourceCode":"\treturn applyInlineExpansionsRecursive(steps, parser, 0)\n}\n\n// applyInlineExpansionsRecursive handles inline expansions for a slice of steps.\n// depth tracks recursion to prevent infinite expansion loops.\nfunc applyInlineExpansionsRecursive(steps []*Step, parser *Parser, depth int) ([]*Step, error) {\n\tif depth > DefaultMaxExpansionDepth {\n\t\treturn nil, fmt.Errorf(\"inline expansion depth limit exceeded: max %d levels\", DefaultMaxExpansionDepth)\n\t}\n\n\tvar result []*Step\n\n\tfor _, step := range steps {\n\t\t// Check if this step has an inline expansion\n\t\tif step.Expand != \"\" {\n\t\t\t// Load the expansion formula\n\t\t\texpFormula, err := parser.LoadByName(step.Expand)\n\t\t\tif err != nil {\n\t\t\t\treturn nil, fmt.Errorf(\"inline expand on step %q: loading %q: %w\", step.ID, step.Expand, err)\n\t\t\t}\n\n\t\t\tif expFormula.Type != TypeExpansion {\n\t\t\t\treturn nil, fmt.Errorf(\"inline expand on step %q: %q is not an expansion formula (type=%s)\",\n\t\t\t\t\tstep.ID, step.Expand, expFormula.Type)\n\t\t\t}\n\n\t\t\tif len(expFormula.Template) == 0 {\n\t\t\t\treturn nil, fmt.Errorf(\"inline expand on step %q: %q has no template steps\", step.ID, step.Expand)\n\t\t\t}\n\n\t\t\t// Merge formula default vars with step's ExpandVars overrides\n\t\t\tvars := mergeVars(expFormula, step.ExpandVars)\n\n\t\t\t// Expand the step using the template (reuse existing expandStep)\n\t\t\texpandedSteps, err := expandStep(step, expFormula.Template, 0, vars)\n\t\t\tif err != nil {\n\t\t\t\treturn nil, fmt.Errorf(\"inline expand on step %q: %w\", step.ID, err)","sourceCodeStart":454,"sourceCodeEnd":490,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/formula/expand.go#L454-L490","documentation":"Thrown when a step's Expand field names a formula that parser.LoadByName cannot find or load. The underlying load error (not found, unreadable file, parse failure) is wrapped with %w so the root cause appears in the message. It means the inline expansion reference cannot be resolved against the configured formula search paths.","triggerScenarios":"ApplyInlineExpansions encounters step.Expand set to a name with no matching formula file in any search path (.beads/formulas in repo, ~/.beads/formulas, GT_ROOT), or the formula file exists but fails to load (unreadable, unparseable).","commonSituations":"Typo in the Expand value; formula file not committed or missing from a checkout; formula defined in a search path not configured (GT_ROOT unset); formula file has a syntax error so LoadByName's parse fails.","solutions":["Verify the Expand name exactly matches the formula's `formula` field and that its file exists under one of the search paths (.beads/formulas, ~/.beads/formulas, $GT_ROOT/.beads/formulas).","Read the wrapped root-cause error: if it's a parse/read error, fix the formula file itself; if 'not found', add or correct the file location.","Set GT_ROOT or place the formula in the repo's .beads/formulas directory so shared formulas resolve.","Run bd formula listing to confirm the formula is discoverable by the parser."],"exampleFix":"// before\n[[step]]\nid = \"scaffold\"\nexpand = \"scafolding\"   # typo: formula not found\n// after\n[[step]]\nid = \"scaffold\"\nexpand = \"scaffolding\"  # matches .beads/formulas/scaffolding.formula.toml","handlingStrategy":"validation","validationCode":"for _, s := range steps {\n\tif s.Expand == \"\" {\n\t\tcontinue\n\t}\n\tif _, err := parser.LoadByName(s.Expand); err != nil {\n\t\treturn fmt.Errorf(\"step %q references unknown expansion %q: %w\", s.ID, s.Expand, err)\n\t}\n}","typeGuard":"func hasResolvableExpand(p *formula.Parser, s *formula.Step) bool {\n\tif s.Expand == \"\" {\n\t\treturn true\n\t}\n\t_, err := p.LoadByName(s.Expand)\n\treturn err == nil\n}","tryCatchPattern":"expanded, err := formula.ApplyInlineExpansions(steps, parser)\nif err != nil {\n\tvar pathErr *fs.PathError\n\tif errors.As(err, &pathErr) && os.IsNotExist(pathErr) {\n\t\treturn fmt.Errorf(\"formula referenced by Expand is missing: %w\", err)\n\t}\n\treturn err\n}","preventionTips":["Commit all referenced formula files under .beads/formulas so every checkout has them.","Spell-check Expand names against the formula's `formula` field; keep names and filenames consistent.","Add a CI lint that loads every formula and resolves every Expand reference."],"tags":["go","formula","file-not-found","inline-expansion"],"backgroundTag":"formula-not-found","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}