{"record":{"id":"02171ddaa76405f8","repo":"gastownhall/beads","slug":"storage-backend-q-in-metadata-json-is-not-recogni","errorCode":null,"errorMessage":"storage backend %q in metadata.json is not recognized or supported; %s; the supported backend is %q; fix or restore metadata.json and retry","messagePattern":"storage backend %q in metadata\\.json is not recognized or supported; (.+?); the supported backend is %q; fix or restore metadata\\.json and retry","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"internal/configfile/backend_messages.go","lineNumber":50,"sourceCode":"}\n\n// RemovedBackendDetail returns the shared body of every removed-backend error:\n// the rationale, the untouched-data guarantee, and the migration path. Callers\n// prepend a site-specific lead-in; RemovedBackendError carries the standard one.\nfunc RemovedBackendDetail(backend string) string {\n\treturn 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)\n}\n\n// RemovedBackendError is the standard fail-closed error for metadata that\n// selects a backend whose direct support was removed.\nfunc RemovedBackendError(backend string) error {\n\treturn fmt.Errorf(\"storage backend %q is no longer supported: %s\", backend, RemovedBackendDetail(backend))\n}\n\n// UnknownBackendError is the standard fail-closed error for metadata that\n// names a backend this build does not recognize.\nfunc UnknownBackendError(backend string) error {\n\treturn 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)\n}\n","sourceCodeStart":32,"sourceCodeEnd":52,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/configfile/backend_messages.go#L32-L52","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Fix or restore metadata.json to use \"dolt\" as the backend, or restore it from git","If the file came from a newer bd, upgrade your bd binary to a matching or newer version","If unsure of correct content, back up the workspace and re-run `bd init`, then import exported data"],"exampleFix":"// before (metadata.json)\n{\"backend\":\"sqllite\"}\n// after\n{\"backend\":\"dolt\"}","handlingStrategy":"type-guard","validationCode":"var m struct{ Backend string `json:\"backend\"` }\nif err := json.Unmarshal(meta, &m); err != nil || m.Backend != \"dolt\" {\n    // restore metadata.json from git or reinstall matching bd before running\n}","typeGuard":"func knownBackend(b string) bool { return b == \"dolt\" }","tryCatchPattern":"if err := bd.Run(...); err != nil {\n    var ube *bd.UnknownBackendError\n    if errors.As(err, &ube) {\n        fmt.Fprintln(os.Stderr, \"unknown backend in metadata.json: fix/restore the file or upgrade bd\")\n        os.Exit(1)\n    }\n    return err\n}","preventionTips":["Track .beads/metadata.json in git so bad edits are recoverable","Resolve merge conflicts in metadata.json explicitly","Pin bd versions across a team to avoid schema drift","Never write speculative values into metadata.json"],"tags":["storage","backend","metadata"],"backgroundTag":"unsupported-storage-backend","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}