gastownhall/beads · error

config key must not be empty

Error message

config key must not be empty

What it means

ValidateSettingKey rejects a config key that is empty or only whitespace, wrapping issueops.ErrValidation. A key must name something: an empty key is meaningless because the 'not set' answer it would produce corresponds to a question nobody asked. The key is returned unchanged when valid.

Source

Thrown at internal/workapi/workspaceconfig.go:33

//
// It lives here for the reason those do: three implementations of
// issueops.WorkspaceConfig have to agree about it, and it is checkable without
// a database. The conformance contract is left to pin what only a real backend
// can show — that the row and its projection land together.
//
// It is deliberately NOT the whole of `bd config set`. Which SOURCE a key
// belongs to (config.yaml, git config, this plane) is resolved by the front
// door; see issueops/workspaceconfig.go.

// ValidateSettingKey checks a key a caller wants to READ or REMOVE, and
// returns it unchanged.
//
// The only rule at this end is that a key has to name something: an empty key
// answered with the empty value an unset key returns would report "not set"
// for a question nobody asked.
func ValidateSettingKey(key string) (string, error) {
	if strings.TrimSpace(key) == "" {
		return "", fmt.Errorf("%w: config key must not be empty", issueops.ErrValidation)
	}
	return key, nil
}

// ValidateSettingWrite checks a key and value a caller wants to STORE, and
// returns the value as it will be stored, so that a body cannot store a
// different string from the one that was checked.
func ValidateSettingWrite(key, value string) (string, error) {
	if _, err := ValidateSettingKey(key); err != nil {
		return "", err
	}
	// The prefix is owned by bd init --prefix, bd bootstrap and bd
	// rename-prefix. Refused HERE rather than at the front door because `bd
	// config set` is not the only door that reaches this plane: before this
	// role existed `bd config set-many issue_prefix=x` walked past the guard
	// and re-prefixed the workspace.
	if key == issueops.SettingKeyIssuePrefix || key == "issue-prefix" {
		return "", fmt.Errorf("%w: %q is set by bd init --prefix, bd bootstrap or bd rename-prefix, not by a config write: "+

View on GitHub (pinned to 71377f2769)

Solutions

  1. Supply a non-empty setting key (e.g. issue_prefix, status.custom) before calling the API
  2. Trim and check the key in the caller: if strings.TrimSpace(key)=="" bail out with a clearer user-facing message
  3. If the key comes from a variable or config file, verify the variable is populated and the parse didn't yield an empty token

Example fix

// before
v, err := ValidateSettingWrite(key, value)
// after
if strings.TrimSpace(key) == "" {
    return fmt.Errorf("--key is required, got %q", key)
}
v, err := ValidateSettingWrite(key, value)
Defensive patterns

Strategy: validation

Validate before calling

func validKey(k string) bool { return strings.TrimSpace(k) != "" }
if !validKey(key) { return fmt.Errorf("config key must not be empty") }

Type guard

func hasSettingKey(k string) bool { return strings.TrimSpace(k) != "" }

Try / catch

v, err := workapi.ValidateSettingWrite(key, val)
if errors.Is(err, issueops.ErrValidation) { /* surface 'key required' to user */ }

Prevention

When it happens

Trigger: Calling ValidateSettingKey("") or ValidateSettingKey(" ") directly, or any code path through ValidateSettingWrite that passes a blank key (e.g. bd config set "" x, or a parsed config body with an empty key field).

Common situations: CLI/scripts building config set commands from shell variables that are unset or empty; JSON/YAML request bodies where the key field was omitted or left as an empty string; string splitting that produced an empty token (e.g. 'bd config set =value' splitting on '=').

Related errors

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