{"record":{"id":"9f811b8f1aaa9ba9","repo":"gastownhall/beads","slug":"load-s-w-refusing-to-fall-back-to-the-embedded","errorCode":null,"errorMessage":"load %s: %w (refusing to fall back to the embedded store)","messagePattern":"load (.+?): %w \\(refusing to fall back to the embedded store\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"cmd/bd/store_factory.go","lineNumber":261,"sourceCode":"// refuses because that repo has not been migrated yet — and it must certainly\n// not migrate it.\nfunc newPreviewStoreFromConfig(ctx context.Context, beadsDir string) (storage.DoltStorage, error) {\n\treturn openNonMutatingStoreFromConfig(ctx, beadsDir, true)\n}\n\n// openNonMutatingStoreFromConfig deliberately does NOT activate the events\n// journal: every arm below opens a store that refuses writes (OpenReadOnly,\n// OpenForPreviewCommand, ReadOnly server config), so there is no mutation for a\n// journal row to accompany. Registered in the construction guard's exemption\n// list with that reason.\nfunc openNonMutatingStoreFromConfig(ctx context.Context, beadsDir string, preview bool) (storage.DoltStorage, error) {\n\tcfg, err := configfile.Load(beadsDir)\n\tif err != nil {\n\t\t// Same contract as newDoltStoreFromConfig: a present-but-unloadable\n\t\t// metadata.json is a hard error, not a silent embedded fallback —\n\t\t// and the error must name the real cause rather than the downstream\n\t\t// \"database not found\" the embedded open would produce.\n\t\treturn nil, fmt.Errorf(\"load %s: %w (refusing to fall back to the embedded store)\", configfile.ConfigPath(beadsDir), err)\n\t}\n\tif err := validateConfiguredBackend(cfg); err != nil {\n\t\treturn nil, err\n\t}\n\tcfg = normalizeLoadedConfig(cfg)\n\tif backend, ok := backends.Lookup(cfg.GetBackend()); ok {\n\t\treturn backend.OpenReadOnly(ctx, beadsDir)\n\t}\n\tif cfg != nil && cfg.IsDoltProxiedServerMode() {\n\t\t// TODO: this needs to be uow provider\n\t\treturn nil, fmt.Errorf(\"proxy server store needs to be uow provider\")\n\t\t// return newProxiedServerStore(ctx, &dolt.Config{\n\t\t// \tBeadsDir:      beadsDir,\n\t\t// \tDatabase:      cfg.GetDoltDatabase(),\n\t\t// \tProxiedServer: true,\n\t\t// \tReadOnly:      true,\n\t\t// })\n\t}","sourceCodeStart":243,"sourceCodeEnd":279,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/store_factory.go#L243-L279","documentation":"openNonMutatingStoreFromConfig treats a present-but-unloadable metadata.json as a hard error, mirroring newDoltStoreFromConfig's contract: no silent fallback to the embedded store. The error names the config path, the underlying cause, and explicitly says the embedded fallback was refused, so callers see the real cause instead of a misleading downstream \"database not found\".","triggerScenarios":"newReadOnlyStoreFromConfig or newPreviewStoreFromConfig (read-only bd commands) invoked in a workspace where metadata.json exists but configfile.Load fails (malformed JSON, unreadable, parse error).","commonSituations":"Corrupt or truncated metadata.json after a crash; hand-edited config with invalid JSON; permission changes after repo clone; read-only command run by a user who cannot read the config.","solutions":["Validate and repair metadata.json (the path named in the error) — it must be valid JSON.","Restore the file from git or regenerate it via bd init/backend setup.","Fix read permissions for the invoking user.","Use errors.Unwrap on the returned error for the precise parse/I/O cause."],"exampleFix":"python3 -m json.tool .beads/metadata.json   # locate the parse error\ngit checkout -- .beads/metadata.json        # or repair by hand, then retry","handlingStrategy":"try-catch","validationCode":"data, err := os.ReadFile(configfile.ConfigPath(beadsDir))\nif err == nil {\n    if err := json.Valid(data); !err {\n        // metadata.json is malformed; repair before any read-only command\n    }\n}","typeGuard":null,"tryCatchPattern":"store, err := newReadOnlyStoreFromConfig(ctx, beadsDir)\nif err != nil {\n    // a present-but-unloadable metadata.json is a hard error; no embedded fallback\n    return fmt.Errorf(\"read-only open: %w\", err)\n}","preventionTips":["Validate metadata.json after every manual edit (json.Valid).","Restore corrupt configs from git rather than working around them.","Ensure the invoking user can read .beads/metadata.json.","Do not expect silent embedded fallback for read-only/preview commands — it is deliberately refused."],"tags":["read-only","metadata","configuration","storage"],"backgroundTag":"corrupt-config-file","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}