gastownhall/beads · critical

storage backend %q in metadata.json is not recognized or sup

Error message

storage backend %q in metadata.json is not recognized or supported; %s; the supported backend is %q; fix or restore metadata.json and retry

What it means

UnknownBackendError is the fail-closed error when metadata.json names a backend this build does not recognize at all. bd refuses to proceed, guarantees nothing was opened or modified, and points at the single supported backend (dolt).

Source

Thrown at internal/configfile/backend_messages.go:50

}

// RemovedBackendDetail returns the shared body of every removed-backend error:
// the rationale, the untouched-data guarantee, and the migration path. Callers
// prepend a site-specific lead-in; RemovedBackendError carries the standard one.
func RemovedBackendDetail(backend string) string {
	return fmt.Sprintf("%s; the configured %s database was not opened or modified; export it with a bd version that supports %s, then follow bd help init-safety to reinitialize with Dolt and import the exported data", removedBackendRationale(backend), backend, backend)
}

// RemovedBackendError is the standard fail-closed error for metadata that
// selects a backend whose direct support was removed.
func RemovedBackendError(backend string) error {
	return fmt.Errorf("storage backend %q is no longer supported: %s", backend, RemovedBackendDetail(backend))
}

// UnknownBackendError is the standard fail-closed error for metadata that
// names a backend this build does not recognize.
func UnknownBackendError(backend string) error {
	return fmt.Errorf("storage backend %q in metadata.json is not recognized or supported; %s; the supported backend is %q; fix or restore metadata.json and retry", backend, BackendNotOpenedGuarantee, BackendDolt)
}

View on GitHub (pinned to 71377f2769)

Solutions

1. Fix or restore metadata.json to use "dolt" as the backend, or restore it from git
2. If the file came from a newer bd, upgrade your bd binary to a matching or newer version
3. If unsure of correct content, back up the workspace and re-run `bd init`, then import exported data

Example fix

// before (metadata.json)
{"backend":"sqllite"}
// after
{"backend":"dolt"}

var m struct{ Backend string `json:"backend"` }
if err := json.Unmarshal(meta, &m); err != nil || m.Backend != "dolt" {
    // restore metadata.json from git or reinstall matching bd before running
}

func knownBackend(b string) bool { return b == "dolt" }

if err := bd.Run(...); err != nil {
    var ube *bd.UnknownBackendError
    if errors.As(err, &ube) {
        fmt.Fprintln(os.Stderr, "unknown backend in metadata.json: fix/restore the file or upgrade bd")
        os.Exit(1)
    }
    return err
}

When it happens

Trigger: Running bd where .beads/metadata.json contains an unknown backend string (typo, hand-edited file, or file written by a newer bd version); returned during backend resolution.

Common situations: Manual edits to metadata.json, merge conflicts garbling the file, or opening a repo created by a much newer bd release with an older binary.

Related errors

• configured storage backend %q in metadata.json is not recogn
• not using Dolt backend (configured backend %q)
• storage backend has no underlying database
• load %s: %w
• persisting sanitized database name to metadata.json: %w

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