{"record":{"id":"04f19474a313af2f","repo":"gastownhall/beads","slug":"loading-config-w-04f194","errorCode":null,"errorMessage":"loading config: %w","messagePattern":"loading config: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/bd/legacy_upgrade_guard.go","lineNumber":31,"sourceCode":"\t\"github.com/steveyegge/beads/internal/doltserver\"\n\t\"github.com/steveyegge/beads/internal/git\"\n\t\"github.com/steveyegge/beads/internal/storage/embeddeddolt\"\n\t\"github.com/steveyegge/beads/internal/utils\"\n\t\"golang.org/x/mod/semver\"\n)\n\n// guardLegacyUpgradeWorkspace rejects the reviewed pre-Dolt and legacy-Dolt\n// workspace shapes before command setup can track a version, migrate metadata,\n// or construct a store. It intentionally classifies only metadata, regular\n// SQLite files, and the bounded local version witness; storage internals stay\n// behind the driver boundary.\nfunc guardLegacyUpgradeWorkspace(beadsDir string) error {\n\tif beadsDir == \"\" {\n\t\treturn nil\n\t}\n\tcfg, err := configfile.LoadForDiscovery(beadsDir)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"loading config: %w\", err)\n\t}\n\tif isHistoricalSQLiteWorkspace(beadsDir, cfg) {\n\t\treturn legacyUpgradeRefusal(\"historical SQLite workspace\")\n\t}\n\t// Validate read-only discovery metadata before any caller can use Load,\n\t// which migrates legacy config.json to metadata.json. Removed and unknown\n\t// backends must fail without changing the only pointer to their data.\n\tif err := validateConfiguredBackend(cfg); err != nil {\n\t\treturn err\n\t}\n\tserverMode := cfg != nil && strings.EqualFold(cfg.DoltMode, configfile.DoltModeServer)\n\tif embeddeddolt.HasRepository(beadsDir) && !serverMode {\n\t\treturn nil\n\t}\n\tversion, present := legacyUpgradeVersionWitness(beadsDir)\n\tif serverMode && present && legacyServerVersion(version) {\n\t\treturn legacyUpgradeRefusal(fmt.Sprintf(\"legacy Dolt server workspace from bd %s\", version))\n\t}","sourceCodeStart":13,"sourceCodeEnd":49,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/legacy_upgrade_guard.go#L13-L49","documentation":"guardLegacyUpgradeWorkspace loads the workspace config via configfile.LoadForDiscovery and wraps any load failure as \"loading config: %w\". Called before any upgrade/guard decision (doctor validation, legacy workspace discovery), it protects against unreadable or malformed config in the .beads directory. The root cause (parse error, IO error, schema error) is preserved in the chain.","triggerScenarios":"Running bd commands that hit guardLegacyUpgradeWorkspace (doctor workspace validation, upgrade guards) in a workspace whose config.json/metadata.json cannot be loaded — malformed JSON, unreadable file, or discovery-time validation failure.","commonSituations":"Hand-edited config.json with JSON syntax errors; .beads directory with wrong permissions; partially migrated workspace mixing legacy and new config files; interrupted upgrade leaving truncated metadata.json.","solutions":["Inspect the wrapped root cause — usually a JSON parse or file permission error naming the config file","Validate/repair the JSON in .beads/metadata.json (or legacy config.json); restore from git if the workspace is tracked","Check file permissions/ownership of the .beads directory","If migrating from legacy SQLite, back up .beads and let the upgrade tooling regenerate config"],"exampleFix":"// before (malformed)\n{\"database\": \"beads.db\",,}\n// after\n{\"database\": \"beads.db\"}","handlingStrategy":"validation","validationCode":"// pre-validate workspace config JSON before running guarded commands\npython3 -m json.tool .beads/metadata.json > /dev/null || echo \"config JSON is malformed\"","typeGuard":null,"tryCatchPattern":"if err := guardLegacyUpgradeWorkspace(beadsDir); err != nil {\n    var perr *json.SyntaxError\n    if errors.As(err, &perr) { /* repair JSON at perr.Offset */ }\n    return err\n}","preventionTips":["Don't hand-edit .beads config files without validating JSON afterward","Track .beads config in git so you can restore a known-good version","Check file permissions on .beads before running doctor/upgrade commands","Back up .beads before any legacy SQLite to Dolt migration"],"tags":["config","workspace","upgrade-guard","json"],"backgroundTag":"config-load-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}