What causes "invalid variable format '%s', expected 'key=value'" in gastownhall/beads?

Pass variables as key=value: `--var count=3`.

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

Error message

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

What it means

parseVarFlags converts repeated --var flags into a key=value map. Any flag string without an '=' separator cannot be split into key and value, so it throws "invalid variable format '%s', expected 'key=value'" naming the offending argument.

Source

Thrown at cmd/bd/pour.go:81

	attachType string
}

func gatherPourInput(cmd *cobra.Command, args []string) pourInput {
	in := pourInput{protoArg: args[0]}
	in.dryRun, _ = cmd.Flags().GetBool("dry-run")
	in.varFlags, _ = cmd.Flags().GetStringArray("var")
	in.assignee, _ = cmd.Flags().GetString("assignee")
	in.attachArgs, _ = cmd.Flags().GetStringSlice("attach")
	in.attachType, _ = cmd.Flags().GetString("attach-type")
	return in
}

func parseVarFlags(varFlags []string) (map[string]string, error) {
	vars := 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)
		}
		vars[parts[0]] = parts[1]
	}
	return vars, nil
}

func runPour(cmd *cobra.Command, args []string) error {
	CheckReadonly("pour")

	evt := metrics.NewCommandEvent("pour")
	defer func() {
		if c := metrics.Global(); c != nil {
			c.CloseEventAndAdd(evt)
		}
	}()

	in := gatherPourInput(cmd, args)

View on GitHub (pinned to 71377f2769)

Solutions

Pass variables as key=value: `--var count=3`.
Quote the whole argument if the value contains spaces: `--var "msg=hello world"`.
Check each --var flag in the failing command for a missing '='.
Use an empty value explicitly if intended: `--var key=`.

Example fix

// before
bd pour molecule --var count
// error: invalid variable format 'count', expected 'key=value'
// after
bd pour molecule --var count=3

Defensive patterns

Strategy: validation

Validate before calling

func validVarFlag(s string) bool {
    return strings.Contains(s, "=") && strings.SplitN(s, "=", 2)[0] != ""
}
// check each --var flag before invoking the command

Type guard

func isKeyValue(s string) (key, val string, ok bool) {
    parts := strings.SplitN(s, "=", 2)
    if len(parts) != 2 || parts[0] == "" {
        return "", "", false
    }
    return parts[0], parts[1], true
}

Try / catch

vars, err := parseVarFlags(varFlags)
if err != nil {
    if strings.HasPrefix(err.Error(), "invalid variable format") {
        return fmt.Errorf("usage: --var key=value (got: %s)", err)
    }
    return err
}

Prevention

Always pass variables as key=value
Quote arguments containing spaces or special characters
Validate --var flags in shell wrappers before invoking bd
Use --var key= for intentionally empty values

When it happens

Trigger: Passing a --var argument with no '=' (e.g. --var foo or --var "foo=") ... specifically any v where strings.SplitN(v, "=", 2) yields fewer than 2 parts — to commands using parseVarFlags: bd pour, wisp create, gatherMolBondInput, or the proxied pour server.

Common situations: Users writing `bd pour mol --var count` instead of `--var count=3`; shell quoting stripping the '=' (rare); copy-pasting flag docs where the example value was omitted.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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