What causes "invalid mode '%s', must be 'compile' or 'runtime'" in gastownhall/beads?

Use --mode compile or --mode runtime (lowercase, exact)

invalid mode ' ', must be 'compile' or 'runtime

Error message

invalid mode '%s', must be 'compile' or 'runtime'

What it means

parseCookFlags validates the --mode flag for `bd cook`. Only 'compile' and 'runtime' are accepted (empty string is allowed and means auto-select). Any other value produces this error listing the two valid choices. Runtime mode is also implicitly triggered by providing --var flags.

Solutions

Use --mode compile or --mode runtime (lowercase, exact)
Omit --mode entirely and let runtime mode auto-trigger from --var flags
Normalize the value in wrapper scripts, e.g. mode=$(echo "$MODE" | tr 'A-Z' 'a-z') and validate before calling bd

Example fix

// before
bd cook formula --mode Runtime
// after
bd cook formula --mode runtime

Defensive patterns

Strategy: validation

Validate before calling

// validate mode before invoking bd cook
var allowed = map[string]bool{"": true, "compile": true, "runtime": true}
if !allowed[mode] {
  return fmt.Errorf("invalid mode %q, must be 'compile' or 'runtime'", mode)
}

Try / catch

if err := parseCookFlags(...); err != nil {
  if strings.Contains(err.Error(), "invalid mode") {
    // print usage: --mode compile|runtime
  }
  return err
}

Prevention

Use only the exact lowercase values compile and runtime
Prefer omitting --mode; cook auto-selects runtime when --var flags are present
Whitelist/normalize the mode value in wrapper scripts before passing it through

When it happens

Trigger: Invoking `bd cook` with `--mode production`, `--mode run`, `--mode RUN`, or any value other than exactly compile/runtime/empty — the comparison is case-sensitive.

Common situations: Guessing mode names from other tools (prod/dev/run); capitalization slip (--mode Runtime); reusing a script that passed an unrelated tool's mode flag through to cook.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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

Appendix: source

Thrown at cmd/bd/cook.go:133

	force, _ := cmd.Flags().GetBool("force")
	searchPaths, _ := cmd.Flags().GetStringSlice("search-path")
	prefix, _ := cmd.Flags().GetString("prefix")
	varFlags, _ := cmd.Flags().GetStringArray("var")
	mode, _ := cmd.Flags().GetString("mode")

	// Parse variables
	inputVars := make(map[string]string)
	for _, v := range varFlags {
		parts := strings.SplitN(v, "=", 2)
		if len(parts) != 2 {
			return nil, fmt.Errorf("invalid variable format '%s', expected 'key=value'", v)
		}
		inputVars[parts[0]] = parts[1]
	}

	// Validate mode
	if mode != "" && mode != "compile" && mode != "runtime" {
		return nil, fmt.Errorf("invalid mode '%s', must be 'compile' or 'runtime'", mode)
	}

	// Runtime mode is triggered by: explicit --mode=runtime OR providing --var flags
	runtimeMode := mode == "runtime" || len(inputVars) > 0

	return &cookFlags{
		dryRun:      dryRun,
		persist:     persist,
		force:       force,
		searchPaths: searchPaths,
		prefix:      prefix,
		inputVars:   inputVars,
		runtimeMode: runtimeMode,
		formulaPath: args[0],
	}, nil
}

// loadAndResolveFormula parses a formula file and applies all transformations.

View on GitHub (pinned to 71377f2769)