gastownhall/beads · error

invalid variable format '%s', expected 'key=value'

Error message

invalid variable format '%s', expected 'key=value'

What it means

parseCookFlags in cmd/bd/cook.go parses repeated --var flags for the `bd cook` command. Each value must be of the form key=value; strings.SplitN(v, "=", 2) must yield exactly 2 parts. Any --var value without an '=' separator produces this error naming the offending value.

Source

Thrown at cmd/bd/cook.go:126

	formulaPath string
}

// parseCookFlags parses and validates cook command flags
func parseCookFlags(cmd *cobra.Command, args []string) (*cookFlags, error) {
	dryRun, _ := cmd.Flags().GetBool("dry-run")
	persist, _ := cmd.Flags().GetBool("persist")
	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,

View on GitHub (pinned to 71377f2769)

Solutions

1. Write the flag as key=value with a literal equals sign: --var key=value
2. Quote the whole argument so the shell does not split it: --var "key=some value"
3. Fix empty shell-variable expansions before invoking cook (e.g. ${KEY:?unset})

Example fix

// before
bd cook formula --var debug
// after
bd cook formula --var debug=true

// validate --var values before invoking bd cook
for _, v := range varFlags {
  if !strings.Contains(v, "=") || strings.HasPrefix(v, "=") {
    return fmt.Errorf("invalid variable format %q, expected 'key=value'", v)
  }
}

if err := parseCookFlags(...); err != nil {
  if strings.Contains(err.Error(), "invalid variable format") {
    // print usage: --var must be key=value
  }
  return err
}

When it happens

Trigger: Invoking `bd cook` with a --var flag whose value has no '=', e.g. `--var debug`, `--var =true` is accepted? No — the exact trigger is any v where SplitN(v,"=",2) returns one part: `--var debug` (no '='), or an empty value `--var ""`.

Common situations: Shell variable expansion failing (`--var $KEY` with KEY empty), quoting mistakes that split key=value into two argv entries (`--var key value`), copying docs examples where 'key=value' was meant literally as a template.

Related errors

• invalid mode '%s', must be 'compile' or 'runtime'
• runtime mode requires all variables to have values Missing:
• invalid dependency format %q, expected 'type:id' or 'id'
• cannot combine %s
• resolving issue ID %q: %w (to %s multiple labels, pass one c

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