gastownhall/beads · error

key cannot be empty

Error message

key cannot be empty

What it means

`bd kv set` validates every key through validateKVKey before writing to the KV store. An empty key gives the store nothing to address, so the CLI rejects it up front with this message instead of writing an unidentifiable record. It is the first of several guard clauses in the same validator.

Source

Thrown at cmd/bd/kv.go:22

	"fmt"
	"os"
	"sort"
	"strings"

	"github.com/spf13/cobra"

	"github.com/steveyegge/beads/internal/metrics"
	"github.com/steveyegge/beads/internal/storage/kvkeys"
)

// kvPrefix is prepended to all user keys to separate them from internal config
const kvPrefix = kvkeys.Prefix

// validateKVKey checks if a key is valid for the KV store.
// Returns an error if the key is invalid.
func validateKVKey(key string) error {
	if key == "" {
		return fmt.Errorf("key cannot be empty")
	}
	if strings.TrimSpace(key) == "" {
		return fmt.Errorf("key cannot be only whitespace")
	}
	// Prevent keys that would create nested kv.kv.* prefixes
	if strings.HasPrefix(key, kvPrefix) {
		return fmt.Errorf("key cannot start with 'kv.' (would create nested prefix)")
	}
	// Reserve the persistent-memory namespace: a generic memory.* key would
	// store to kv.memory.*, indistinguishable from a `bd remember` memory, and
	// the merge resolver auto-resolves kv.memory.* conflicts with --theirs
	// (GH#2474). Without this guard a user's deliberate kv value could be
	// silently overridden by a remote on pull. Keep the namespace owned by
	// bd remember / bd forget.
	if strings.HasPrefix(key, kvkeys.MemoryPrefix) {
		return fmt.Errorf("key cannot start with %q (reserved for persistent memories; use 'bd remember' / 'bd forget')", kvkeys.MemoryPrefix)
	}
	// Prevent keys that look like internal config

View on GitHub (pinned to 71377f2769)

Solutions

1. Re-run with a non-empty key: bd kv set <key> <value>.
2. Check the variable or template that produced the key; ensure it is populated before invoking bd.
3. Use `bd kv set` interactively first to confirm the key name you intend.

Example fix

// before
KEY=""; bd kv set "$KEY" "v"
// after
KEY="my-setting"; bd kv set "$KEY" "v"

if [ -z "$KEY" ]; then echo "key must be non-empty" >&2; exit 1; fi
bd kv set "$KEY" "$VALUE"

When it happens

Trigger: Running `bd kv set "" <value>` or calling validateKVKey("") via the kv set/kv get code paths with an empty string key, e.g. from a script whose key variable is unset.

Common situations: Shell scripts where a variable holding the key name is empty/unset (`bd kv set "$KEY" "$VAL"` with KEY undefined); JSON/YAML templating that drops the key field.

Related errors

• key cannot be only whitespace
• key cannot start with 'kv.' (would create nested prefix)
• key cannot start with %q (reserved for persistent memories;
• key cannot start with reserved prefix %q
• got %d close reasons for %d issue IDs; provide exactly one s

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