gastownhall/beads · error

unknown backend %q (want one of: %s)

Error message

unknown backend %q (want one of: %s)

What it means

Backend.Validate checks that a Backend string is non-empty and one of the recognized constants: external, local-server, local-shared-server. This error is returned when the value is set but not recognized, listing the valid set. The library throws it because the proxy dispatches to a concrete DatabaseServer by backend name and cannot dispatch an unknown value.

Source

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

// 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 to one of the listed valid values: external, local-server, or local-shared-server (exact spelling, lowercase)
2. Check the exact %q value in the error message against your flag/config for typos and casing
3. Check your beads version's supported backends (bd --help / KnownBackendNames) if upgrading from an older release
4. Remove stale config keys that override the backend with an old value

Example fix

// before
b := proxy.Backend("dolt")
if err := b.Validate(); err != nil { ... } // unknown backend "dolt"
// after
b := proxy.Backend("local-server")
if err := b.Validate(); err != nil { ... }

b := proxy.Backend(cfg.Backend)
if !b.Valid() {
    return fmt.Errorf("invalid backend %q (want one of: %s)",
        string(b), strings.Join(proxy.KnownBackendNames(), ", "))
}

func validBackend(s string) (proxy.Backend, bool) {
    b := proxy.Backend(s)
    return b, b.Valid()
}

if err := backend.Validate(); err != nil {
    // list the accepted values in your own message so users can self-correct
    return fmt.Errorf("--backend flag invalid: %w", err)
}

When it happens

Trigger: Calling Backend.Validate (directly or via NewDoltServerUOWProvider) with a backend string that is not one of external/local-server/local-shared-server — e.g. a misspelled value, wrong casing (Local-Server), a deprecated backend name from an older version, or a --backend flag passed an unsupported value.

Common situations: Typo in config file or CLI flag (--backend=dolt instead of local-server), config written for an older beads version using a since-renamed backend name, case-sensitivity mistakes, or hand-edited YAML/JSON with an invalid enum value.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• ExternalDoltConfig: TLSCert set without TLSKey
• remote URL cannot be empty
• directory path is empty
• %w: invalid persistence mode %q
• %w: invalid issue type %s

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