{"record":{"id":"050223dd99b5f540","repo":"gastownhall/beads","slug":"failed-to-open-database-w-hint-s","errorCode":null,"errorMessage":"failed to open database: %w\nHint: %s","messagePattern":"failed to open database: %w\nHint: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"cmd/bd/direct_mode.go","lineNumber":51,"sourceCode":"\tlockStore()\n\tactive := isStoreActive() && getStore() != nil\n\tunlockStore()\n\tif active {\n\t\treturn nil\n\t}\n\n\t// Find the .beads directory\n\tbeadsDir := beads.FindBeadsDir()\n\tif beadsDir == \"\" {\n\t\treturn fmt.Errorf(\"%w.\\n\"+\n\t\t\t\"Hint: run 'bd init' to create a database in the current directory\", ErrNoBeadsDatabase)\n\t}\n\n\t// Use the factory to create the appropriate backend\n\t// based on metadata.json configuration and build tags\n\tstore, err := newDoltStoreFromConfig(ctx, beadsDir)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to open database: %w\\nHint: %s\", err, diagHint())\n\t}\n\n\t// Update the database path for compatibility with code that expects it\n\tif dbPath := beads.FindDatabasePath(); dbPath != \"\" {\n\t\tsetDBPath(dbPath)\n\t}\n\n\tlockStore()\n\tsetStore(store)\n\tsetStoreActive(true)\n\tunlockStore()\n\n\treturn nil\n}\n","sourceCodeStart":33,"sourceCodeEnd":66,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/direct_mode.go#L33-L66","documentation":"Once a .beads directory is found, ensureStoreActiveWithContext opens the storage backend via newDoltStoreFromConfig, which respects metadata.json configuration and build tags. If opening fails — corrupted database, bad metadata.json, missing Dolt files, incompatible version — the error is wrapped as 'failed to open database' with a diagnostic hint from diagHint(). Unlike ErrNoBeadsDatabase, the workspace exists but its storage cannot be opened.","triggerScenarios":"Running a bd command in a valid workspace where newDoltStoreFromConfig fails: corrupted .beads database files, malformed or wrong-backend metadata.json, missing Dolt binary/engine support, or locked database from another process.","commonSituations":"Interrupted bd process left the database in a bad state; metadata.json points to a backend not compiled into this binary (build tags); version upgrade changed the database format; another bd/dolt process holds a lock; disk corruption.","solutions":["Read the wrapped cause and the diagHint() text; run 'bd doctor' for a store-free diagnosis.","Check .beads/metadata.json backend configuration matches the bd binary you built (build tags).","Ensure no other bd/dolt process is holding the database lock; retry after it exits.","Restore .beads from git/backup, or re-init and re-import from .beads/issues.jsonl.","Upgrade or rebuild bd if the database was written by a newer format."],"exampleFix":"// check backend config matches binary\ncat .beads/metadata.json\n// rebuild with the right backend if needed\ngo build -tags dolt ./cmd/bd","handlingStrategy":"try-catch","validationCode":"// probe metadata and DB presence before opening\nif _, err := os.Stat(filepath.Join(beadsDir, \"metadata.json\")); err != nil {\n    return fmt.Errorf(\"metadata.json missing: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"if err := ensureStoreActive(); err != nil {\n    var inner error\n    if errors.As(err, &inner) || strings.Contains(err.Error(), \"failed to open database\") {\n        return runDoctorRepair() // 'bd doctor' is a store-free repair path\n    }\n    return err\n}","preventionTips":["Run 'bd doctor' periodically to catch storage issues early.","Never kill bd mid-transaction; allow commands to finish.","Keep metadata.json under version control and restore it after corruption.","Build bd with the same backend tags the workspace's metadata.json expects.","Ensure only one bd process accesses the database at a time."],"tags":["go","database","dolt","configuration"],"backgroundTag":"database-open-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}