gastownhall/beads · error

storage backend %q is not registered

Error message

storage backend %q is not registered

What it means

newRegisteredBackendStore returns this error when backends.Lookup(name) finds no registered backend for the configured name. It keeps the root pre-run's registry arm working in both CGO and no-CGO builds; the error means the metadata.json backend value does not correspond to any registered backend implementation in this build.

Source

Thrown at cmd/bd/store_factory_nocgo.go:40

	return false
}

func usesProxiedServer() bool {
	if shouldUseGlobals() {
		return proxiedServerMode
	}
	return cmdCtx != nil && cmdCtx.ProxiedServerMode
}

// newRegisteredBackendStore is the non-CGO twin of the CGO build's registry
// factory: identical, since the backend registry does not depend on CGO. It
// exists here too so the root pre-run's registry arm has one activating
// construction path in both builds.
func newRegisteredBackendStore(ctx context.Context, name, beadsDir string, readOnly bool) (s storage.DoltStorage, err error) {
	defer func() { s, err = activateEventsJournalStore(beadsDir, s, err) }()
	backend, ok := backends.Lookup(name)
	if !ok {
		return nil, fmt.Errorf("storage backend %q is not registered", name)
	}
	if readOnly {
		return backend.OpenReadOnly(ctx, beadsDir)
	}
	return backend.Open(ctx, beadsDir)
}

// newDoltStore applies events-journal activation for the same reason its CGO
// twin does — see the note at the top of events_journal.go.
func newDoltStore(ctx context.Context, cfg *dolt.Config) (s storage.DoltStorage, err error) {
	defer func() { s, err = activateEventsJournalStore(cfg.BeadsDir, s, err) }()
	if cfg.ProxiedServer {
		// TODO: this should not be a store
		// it should be a uow provider
		return nil, fmt.Errorf("proxy server store should be uow provider")
	}
	if !cfg.ServerMode {
		return nil, fmt.Errorf("%s", nocgoEmbeddedErrMsg)

View on GitHub (pinned to 71377f2769)

Solutions

1. Check the backend value in .beads/metadata.json and set it to a registered backend (e.g. the standard Dolt backend name).
2. Verify you are running a build that registers your backend (CGO vs nocgo build differences).
3. Run `bd doctor` / consult the backend registry list to see valid names.
4. Correct any typos in the backend name; match the exact registered identifier.

Example fix

// before (metadata.json)
"backend": "doltdb"
// after
"backend": "dolt"

cfg, _ := configfile.Load(beadsDir)
name := cfg.GetBackend()
if _, ok := backends.Lookup(name); !ok {
    return fmt.Errorf("backend %q not registered in this build; fix metadata.json", name)
}

s, err := newRegisteredBackendStore(ctx, name, beadsDir, readOnly)
if err != nil {
    // backend name unknown: check metadata.json backend value and build variant (cgo vs nocgo)
    return err
}

When it happens

Trigger: metadata.json contains a backend string that is unknown or unregistered (typo, removed backend, backend added only in CGO builds while running the nocgo build); constructing a store with an arbitrary name that was never registered.

Common situations: Hand-edited backend field in metadata.json; switching between CGO and nocgo bd builds with backend-specific registrations; upgrading bd where a backend was renamed; fat-fingered backend names in scripts.

Related errors

• not using Dolt backend (configured backend %q)
• configured storage backend %q is no longer supported and can
• configured storage backend %q in metadata.json is not recogn
• configured storage backend %q cannot be opened as Dolt
• backend must be set

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