gastownhall/beads · error

toml: %w

Error message

toml: %w

What it means

Parser.ParseTOML unmarshals bytes as TOML into the Formula struct and wraps any toml.Unmarshal failure as "toml: ...". Thrown for syntactically invalid TOML or values whose types don't fit the Formula struct fields. Reached from ParseFile for *.formula.toml files.

Source

Thrown at internal/formula/parser.go:184

		return nil, fmt.Errorf("json: %w", err)
	}

	// Set defaults
	if formula.Version == 0 {
		formula.Version = 1
	}
	if formula.Type == "" {
		formula.Type = TypeWorkflow
	}

	return &formula, nil
}

// ParseTOML parses a formula from TOML bytes.
func (p *Parser) ParseTOML(data []byte) (*Formula, error) {
	var formula Formula
	if err := toml.Unmarshal(data, &formula); err != nil {
		return nil, fmt.Errorf("toml: %w", err)
	}

	// Set defaults
	if formula.Version == 0 {
		formula.Version = 1
	}
	if formula.Type == "" {
		formula.Type = TypeWorkflow
	}

	return &formula, nil
}

// Resolve fully resolves a formula, processing extends and expansions.
// Returns a new formula with all inheritance applied.
func (p *Parser) Resolve(formula *Formula) (*Formula, error) {
	// Check for cycles
	if p.resolvingSet[formula.Formula] {

View on GitHub (pinned to 71377f2769)

Solutions

1. Read the toml error's line/column and fix the syntax there.
2. Use [[step]] / [[template]] array-of-tables syntax for repeated sections, not single [section].
3. Validate with a TOML parser (e.g. taplo, python tomllib) before committing.
4. Restore the file from git if a merge corrupted it.

Example fix

// before
[step]        // single table: only one step survives / type error
id = "a"
// after
[[step]]
id = "a"
[[step]]
id = "b"

// probe with a strict TOML decoder before use
var probe formula.Formula
if err := toml.Unmarshal(data, &probe); err != nil {
	return fmt.Errorf("formula TOML invalid: %w", err)
}
if probe.Formula == "" {
	return errors.New("formula TOML missing top-level `formula` field")
}

func isValidFormulaTOML(data []byte) bool {
	var f formula.Formula
	return toml.Unmarshal(data, &f) == nil && f.Formula != ""
}

When it happens

Trigger: ParseFile detects the .formula.toml extension and ParseTOML rejects the bytes: bad TOML syntax (unclosed string, duplicate key, wrong table syntax) or type mismatches (version as string, steps defined as [step] instead of [[step]]).

Common situations: Hand-edited formula with a missing quote or bracket; using [template]/[step] (single table) where [[template]]/[[step]] (array) is required; smart quotes from a doc editor; duplicate keys after a bad merge.

Related errors

• parse %s: %w
• json: %w
• formula has no source path
• encoding TOML: %w
• formula %q not accessible: %w

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/cfe9101c3376328d. Report an issue: GitHub.