{"record":{"id":"bae7dd6168c4b7b6","repo":"gastownhall/beads","slug":"failed-to-load-s-w-refusing-to-reinitialize-au","errorCode":null,"errorMessage":"failed to load %s: %w; refusing to reinitialize automatically (restore the metadata or use --reinit-local after safeguarding existing data)","messagePattern":"failed to load (.+?): %w; refusing to reinitialize automatically \\(restore the metadata or use --reinit-local after safeguarding existing data\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"cmd/bd/init.go","lineNumber":2463,"sourceCode":"// operational and must not be treated as success.\n\nfunc checkExistingBeadsDataAt(beadsDir string, prefix string) error {\n\t// Check if .beads directory exists\n\tif _, err := os.Stat(beadsDir); os.IsNotExist(err) {\n\t\treturn nil // No .beads directory, safe to init\n\t}\n\n\t// metadata.json is authoritative for the configured backend, so resolve it once\n\t// and dispatch. Removed-backend tombstones are marked by metadata\n\t// alone — there is no local Dolt directory to inspect — so a plain\n\t// `bd init` (which defaults to Dolt) must not silently repoint a live SQL\n\t// workspace to a fresh embedded Dolt DB and orphan its issues. --reinit-local\n\t// /--force bypass this (handled by the caller). Invalid metadata must fail closed:\n\t// without an explicit reinitialization request, init may not overwrite the only\n\t// marker for an external or otherwise nonlocal database.\n\tcfg, cfgErr := configfile.LoadForDiscovery(beadsDir)\n\tif cfgErr != nil {\n\t\treturn fmt.Errorf(\"failed to load %s: %w; refusing to reinitialize automatically (restore the metadata or use --reinit-local after safeguarding existing data)\", configfile.ConfigPath(beadsDir), cfgErr)\n\t}\n\tif cfg != nil {\n\t\tif guardErr := validateConfiguredBackend(cfg); guardErr != nil {\n\t\t\treturn guardErr\n\t\t}\n\t}\n\n\tif cfg != nil && cfg.GetBackend() == configfile.BackendDolt {\n\t\tif cfg.IsDoltProxiedServerMode() {\n\t\t\tproxiedRoot, rootErr := resolveProxiedServerRootPath(beadsDir)\n\t\t\tif rootErr != nil {\n\t\t\t\treturn fmt.Errorf(\"resolve proxied server root: %w\", rootErr)\n\t\t\t}\n\t\t\tif info, statErr := os.Stat(proxiedRoot); statErr == nil && info.IsDir() {\n\t\t\t\treturn alreadyInitialized(`\n%s Found existing Dolt database: %s\n\nThis workspace is already initialized.","sourceCodeStart":2445,"sourceCodeEnd":2481,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/init.go#L2445-L2481","documentation":"checkExistingBeadsDataAt loads .beads/metadata.json (via configfile.LoadForDiscovery) to determine the configured backend before deciding whether init may proceed. If the metadata is unreadable or corrupt, init fails closed instead of silently reinitializing a fresh embedded Dolt DB — which would orphan the issues of an external/nonlocal database whose only local marker is that metadata file. The error wraps the load failure and explicitly points at --reinit-local as the override.","triggerScenarios":"Running `bd init` (or --init-if-missing, or the check via checkExistingBeadsData) in a workspace where a .beads directory exists but configfile.LoadForDiscovery(beadsDir) returns an error — corrupt/invalid JSON in .beads/metadata.json, invalid schema fields, or an unreadable metadata file.","commonSituations":"A partially completed init or crash left truncated metadata.json; manual editing introduced invalid JSON or unknown backend values; a merge conflict in metadata.json was resolved badly; file permissions make metadata unreadable; upgrading from an old bd version whose metadata format no longer parses.","solutions":["Restore valid metadata: git checkout .beads/metadata.json (or restore from backup) so bd can discover the configured backend, then re-run bd init.","Validate and hand-repair the JSON (jq . .beads/metadata.json) — fix syntax and ensure the backend field is a supported value.","If the local data is disposable or already safeguarded (backed up, external DB verified reachable), deliberately reinitialize with bd init --reinit-local (or --force).","If the workspace actually points at an external/proxied database, fix connectivity/config so the external database is used instead of reinitializing locally."],"exampleFix":"// before: corrupt metadata\n$ bd init\n# failed to load .beads/metadata.json: unexpected end of JSON input; refusing to reinitialize automatically...\n\n// after: restore from git, then init\n$ git checkout -- .beads/metadata.json\n$ bd init  # discovers existing backend, aborts with 'already initialized' or proceeds safely","handlingStrategy":"validation","validationCode":"// Preflight: verify metadata parses before invoking init paths\nraw, err := os.ReadFile(filepath.Join(beadsDir, \"metadata.json\"))\nif err != nil && !os.IsNotExist(err) {\n    return fmt.Errorf(\"metadata unreadable: %w\", err)\n}\nif raw != nil {\n    if err := json.Valid(raw); !err {\n        return fmt.Errorf(\".beads/metadata.json is not valid JSON; restore it before init\")\n    }\n}","typeGuard":null,"tryCatchPattern":"if err := checkExistingBeadsData(); err != nil {\n    if errors.Is(err, errWorkspaceAlreadyInitialized) {\n        return nil // benign skip\n    }\n    if strings.Contains(err.Error(), \"refusing to reinitialize automatically\") {\n        // corrupt metadata: require explicit operator action (--reinit-local) or restore\n        return err\n    }\n    return err\n}","preventionTips":["Commit .beads/metadata.json to version control so it can be restored after corruption.","Never hand-edit metadata.json without validating with jq or a JSON parser afterwards.","Resolve merge conflicts in metadata.json by choosing one side, never concatenating JSON.","Back up .beads before running init after an interrupted or crashed bd process.","Treat 'refusing to reinitialize' as a stop signal: verify external database data is safe before using --reinit-local."],"tags":["config","metadata","init","fail-closed","data-loss-prevention"],"backgroundTag":"corrupt-metadata-file","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}