{"record":{"id":"c3a9b444c620e4a2","repo":"gastownhall/beads","slug":"not-using-dolt-backend-configured-backend-q","errorCode":null,"errorMessage":"not using Dolt backend (configured backend %q)","messagePattern":"not using Dolt backend \\(configured backend %q\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/bd/backend_support.go","lineNumber":41,"sourceCode":"\t\treturn configfile.UnknownBackendError(cfg.Backend)\n\t}\n}\n\n// registeredBackendWorkspaceIsBeadsDir reports whether metadata selects a\n// backend that has no separately discoverable local database.\nfunc registeredBackendWorkspaceIsBeadsDir(cfg *configfile.Config) bool {\n\tif cfg == nil {\n\t\treturn false\n\t}\n\treturn backends.WorkspaceIsBeadsDir(cfg.GetBackend())\n}\n\nfunc requireDoltBackend(cfg *configfile.Config) error {\n\tif err := validateConfiguredBackend(cfg); err != nil {\n\t\treturn err\n\t}\n\tif cfg != nil && cfg.GetBackend() != configfile.BackendDolt {\n\t\treturn fmt.Errorf(\"not using Dolt backend (configured backend %q)\", cfg.GetBackend())\n\t}\n\treturn nil\n}\n\n// normalizeLoadedConfig substitutes the default config for an absent\n// metadata.json (cfg == nil) so mode inference still runs: a remote host\n// supplied via BEADS_DOLT_SERVER_HOST or config.yaml dolt.host (GH#3545)\n// must select server mode even when no metadata.json exists — otherwise\n// the CLI silently opens the embedded store against a remote-host\n// configuration.\nfunc normalizeLoadedConfig(cfg *configfile.Config) *configfile.Config {\n\tif cfg == nil {\n\t\treturn configfile.DefaultConfig()\n\t}\n\treturn cfg\n}\n\nfunc loadDoltBackendConfig(beadsDir string) (*configfile.Config, error) {","sourceCodeStart":23,"sourceCodeEnd":59,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/backend_support.go#L23-L59","documentation":"requireDoltBackend enforces that the configured storage backend is Dolt. After validateConfiguredBackend passes, if cfg is non-nil and cfg.GetBackend() != BackendDolt, it returns this error embedding the actual backend name in %q. Callers that only support Dolt (e.g. loadDoltBackendConfig) use it to fail fast with a clear mismatch message.","triggerScenarios":"Calling requireDoltBackend (directly or via loadDoltBackendConfig) with a config whose metadata/config file selects a backend other than \"dolt\" (e.g. \"sqlite\", \"jsonl\", \"redis\"), or running tests that exercise a non-Dolt backend configuration.","commonSituations":"A .beads/metadata.json or config file written when the project used a legacy/alternate backend; manually switching backends without migrating; copy-pasting config from a non-Dolt setup; environments where the team standardized on Dolt but one checkout still points elsewhere.","solutions":["Update the backend setting to dolt (via bd's config/metadata mechanism, e.g. re-running the documented init/migrate flow).","Read the %q in the message — it names the current backend so you can find where it is set.","If you must keep the other backend, use the non-Dolt code path/command instead of the Dolt-required one.","Migrate existing data per the backend-migration docs before switching, then verify with the same command that previously failed."],"exampleFix":"// before\n# .beads config\nbackend = \"sqlite\"\n\n// after\nbackend = \"dolt\"   # then rerun the command","handlingStrategy":"validation","validationCode":"cfg, err := loadConfig()\nif err != nil { return err }\nif cfg.GetBackend() != \"dolt\" {\n\treturn fmt.Errorf(\"this command requires the dolt backend; got %q\", cfg.GetBackend())\n}","typeGuard":"func isDoltConfig(cfg *configfile.Config) bool {\n\treturn cfg != nil && cfg.GetBackend() == configfile.BackendDolt\n}","tryCatchPattern":"if err := requireDoltBackend(cfg); err != nil {\n\tvar beErr = err // message embeds current backend via %q\n\tlog.Printf(\"backend mismatch: %v — migrate or switch backend\", beErr)\n\treturn beErr\n}","preventionTips":["Standardize the team on the dolt backend and encode it in the repo bootstrap script.","After cloning, verify the backend before running Dolt-only commands.","When migrating backends, follow the documented migration rather than hand-editing metadata.","Check `backend` in .beads config during CI setup to fail early with a clear message."],"tags":["dolt","backend","configuration","storage"],"backgroundTag":"unsupported-backend","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}