gastownhall/beads · error

backend must be set

Error message

backend must be set

What it means

Backend.Validate returns this error when no backend was specified (empty string). The backend name selects which storage engine implementation the proxy/managed child runs, so an empty value is always a configuration mistake rather than a runtime failure.

Solutions

1. Set the Backend field to a supported value (see KnownBackendNames()) before calling Validate/NewDoltServerUOWProvider
2. Check the empty string early in config loading and emit a clear user-facing message
3. Call b.Validate() right after unmarshalling config to fail fast

Example fix

// before
var cfg Config // Backend left zero-value
p, err := proxy.NewDoltServerUOWProvider(cfg)
// after
cfg.Backend = proxy.BackendDolt
if err := cfg.Backend.Validate(); err != nil { return err }
p, err := proxy.NewDoltServerUOWProvider(cfg)

if cfg.Backend == "" { return errors.New("backend must be set: one of " + strings.Join(proxy.KnownBackendNames(), ", ")) }
if err := cfg.Backend.Validate(); err != nil { return err }

func backendSet(b proxy.Backend) bool { return b != "" }

if err := b.Validate(); err != nil {
    return fmt.Errorf("invalid backend config: %w", err)
}

When it happens

Trigger: Calling Backend("").Validate(), directly or transitively through NewDoltServerUOWProvider when a Backend config field was never set.

Common situations: Constructing a config struct without filling the Backend field; loading config from YAML/JSON where the key is absent; zero-valued struct passed to NewDoltServerUOWProvider.

Understand the failure class

Background: "missing required config value" errors: why libraries refuse to start when a configuration key is empty, unset, or blank — this error's family across 48 libraries.

Related errors

• beadsDir must not be empty
• configured storage backend
• configured storage backend
• configured storage backend
• could not extract a Notion ID from

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

Appendix: source

Thrown at internal/storage/dbproxy/proxy/backend.go:45

}

func (b Backend) String() string { return string(b) }

// Valid reports whether b is one of the recognized constants.
func (b Backend) Valid() bool {
	for _, k := range knownBackends {
		if b == k {
			return true
		}
	}
	return false
}

// Validate returns nil if b is non-empty and recognized; otherwise it
// returns a descriptive error listing the supported set.
func (b Backend) Validate() error {
	if b == "" {
		return errors.New("backend must be set")
	}
	if !b.Valid() {
		return fmt.Errorf("unknown backend %q (want one of: %s)", string(b), strings.Join(KnownBackendNames(), ", "))
	}
	return nil
}

// KnownBackendNames returns the recognized backend identifiers as strings,
// in display order. Useful for CLI help text and validation error messages.
func KnownBackendNames() []string {
	out := make([]string, len(knownBackends))
	for i, k := range knownBackends {
		out[i] = string(k)
	}
	return out
}

View on GitHub (pinned to 71377f2769)