{"record":{"id":"b7fa6b2b59dd5467","repo":"gastownhall/beads","slug":"configured-storage-backend-q-in-metadata-json-is","errorCode":null,"errorMessage":"configured storage backend %q in metadata.json is not recognized and cannot be opened as Dolt; %s","messagePattern":"configured storage backend %q in metadata\\.json is not recognized and cannot be opened as Dolt; (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"internal/storage/dolt/open.go","lineNumber":90,"sourceCode":"// unconditional.\nfunc ApplyResolvedServerPort(beadsDir string, cfg *Config) {\n\tresolved := doltserver.DefaultConfig(beadsDir)\n\tcfg.ServerPort = resolved.Port\n\tcfg.ServerPortSource = resolved.PortSource\n\tcfg.ServerPortSharedServer = resolved.PortSharedServer\n}\n\n// requireDoltBackend keeps metadata-driven callers from bypassing the storage\n// factory and interpreting another backend's workspace as Dolt. Removed backend\n// identifiers deliberately remain recognizable in metadata so this check can fail\n// closed instead of opening a new, empty Dolt database.\nfunc requireDoltBackend(fileCfg *configfile.Config) error {\n\tswitch fileCfg.Backend {\n\tcase configfile.BackendPostgres, configfile.BackendMySQL, configfile.BackendSQLite:\n\t\treturn fmt.Errorf(\"configured storage backend %q is no longer supported and cannot be opened as Dolt: %s\", fileCfg.Backend, configfile.RemovedBackendDetail(fileCfg.Backend))\n\t}\n\tif !configfile.IsSupportedBackend(fileCfg.Backend) {\n\t\treturn fmt.Errorf(\"configured storage backend %q in metadata.json is not recognized and cannot be opened as Dolt; %s\", fileCfg.Backend, configfile.BackendNotOpenedGuarantee)\n\t}\n\tbackend := fileCfg.GetBackend()\n\tif backend != configfile.BackendDolt {\n\t\treturn fmt.Errorf(\"configured storage backend %q cannot be opened as Dolt\", backend)\n\t}\n\treturn nil\n}\n\n// NewFromConfig creates a DoltStore based on the metadata.json configuration.\n// beadsDir is the path to the .beads directory.\nfunc NewFromConfig(ctx context.Context, beadsDir string) (*DoltStore, error) {\n\treturn NewFromConfigWithOptions(ctx, beadsDir, nil)\n}\n\n// NewFromConfigWithCLIOptions creates a DoltStore using the standalone CLI\n// auto-start policy from cmd/bd/main.go. This is for CLI helper paths like\n// `bd doctor` that should behave the same way as normal top-level CLI commands\n// while still honoring externally managed server mode.","sourceCodeStart":72,"sourceCodeEnd":108,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/dolt/open.go#L72-L108","documentation":"Opening a DoltStore was refused because metadata.json contains a backend identifier that is not recognized at all — neither supported (dolt) nor a known removed backend. Beads fails closed rather than opening a new empty Dolt database over unknown data.","triggerScenarios":"Calling NewFromConfigWithOptions / NewFromConfigWithCLIOptions when fileCfg.Backend fails configfile.IsSupportedBackend (typo, empty string, future/unknown identifier).","commonSituations":"Hand-edited or corrupted metadata.json; .beads directory produced by a newer or third-party build; empty backend field after a failed write.","solutions":["Verify metadata.json contents and fix the backend value to \"dolt\" if the data is actually Dolt","Confirm you are pointing at the intended .beads directory","Check beads version compatibility if the directory was written by another tool/version","Restore metadata.json from git or backup if it was corrupted"],"exampleFix":"// before: typo in metadata.json\n{\"backend\": \"doltt\"}\n\n// after\n{\"backend\": \"dolt\"}","handlingStrategy":"validation","validationCode":"// Validate backend identifier before opening\ncfg, _ := configfile.Load(beadsDir)\nif !configfile.IsSupportedBackend(cfg.Backend) {\n    return fmt.Errorf(\"metadata.json has unrecognized backend %q\", cfg.Backend)\n}","typeGuard":null,"tryCatchPattern":"store, err := dolt.NewFromConfigWithOptions(beadsDir, opts)\nif err != nil && strings.Contains(err.Error(), \"not recognized\") {\n    // inspect/repair metadata.json, restore from git or backup\n    return repairMetadata(beadsDir)\n}","preventionTips":["Keep metadata.json under version control (beads does this by default)","Avoid hand-editing metadata.json","Match beads tool version to the version that wrote the directory"],"tags":["storage","backend","configuration","metadata"],"backgroundTag":"unrecognized-storage-backend","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}