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.

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)

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.

Related errors

• identity: invalid proxy secret
• not using Dolt backend (configured backend %q)
• repo %q must use OWNER/REPO or HOST/OWNER/REPO
• repo %q contains an empty path component
• repo %q contains invalid character %q

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