{"record":{"id":"a461aab560535be8","repo":"gastownhall/beads","slug":"database-read-failed-w-jsonl-fallback-read-fail","errorCode":null,"errorMessage":"database read failed: %w; JSONL fallback read failed: %v","messagePattern":"database read failed: %w; JSONL fallback read failed: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"cmd/bd/doctor/maintenance.go","lineNumber":520,"sourceCode":"}\n\n// loadMaintenanceIssues loads issues for maintenance checks.\n// It prefers Dolt (source of truth) and falls back to legacy JSONL for\n// backwards compatibility with non-Dolt installations.\nfunc loadMaintenanceIssues(path string) ([]*types.Issue, error) {\n\tbeadsDir := ResolveBeadsDirForRepo(path)\n\n\tissues, err := loadMaintenanceIssuesFromDatabase(beadsDir)\n\tif err == nil {\n\t\treturn issues, nil\n\t}\n\n\tissues, jsonlErr := loadMaintenanceIssuesFromJSONL(beadsDir)\n\tif jsonlErr == nil {\n\t\treturn issues, nil\n\t}\n\n\treturn nil, fmt.Errorf(\"database read failed: %w; JSONL fallback read failed: %v\", err, jsonlErr)\n}\n\nfunc loadMaintenanceIssuesFromDatabase(beadsDir string) ([]*types.Issue, error) {\n\tctx := context.Background()\n\tstore, err := dolt.NewFromConfigWithCLIOptions(ctx, beadsDir, &dolt.Config{ReadOnly: true})\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\tdefer func() { _ = store.Close() }()\n\n\tephemeral := false\n\treturn store.SearchIssues(ctx, \"\", types.IssueFilter{Ephemeral: &ephemeral})\n}\n\nfunc loadMaintenanceIssuesFromJSONL(beadsDir string) ([]*types.Issue, error) {\n\tjsonlPath := filepath.Join(beadsDir, \"issues.jsonl\")\n\tfile, err := os.Open(jsonlPath) // #nosec G304 - path constructed safely\n\tif err != nil {","sourceCodeStart":502,"sourceCodeEnd":538,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/doctor/maintenance.go#L502-L538","documentation":"loadMaintenanceIssues reads issues from the Dolt database first and falls back to the .beads/issues.jsonl export. This error is returned only when BOTH sources fail: the database read error is wrapped with %w and the JSONL fallback error is embedded with %v. It is the definitive 'no readable issue source' condition for doctor maintenance checks.","triggerScenarios":"loadMaintenanceIssuesFromDatabase fails (dolt store cannot open/config) AND loadMaintenanceIssuesFromJSONL also fails (missing/corrupt/unparseable issues.jsonl).","commonSituations":"Fresh clone where .beads/issues.jsonl was never exported and no local Dolt DB initialized; dolt CLI missing or version-incompatible; database locked or corrupted; JSONL truncated by an interrupted sync; wrong beadsDir path.","solutions":["Run bd dolt pull / bd sync to restore the JSONL export or database from the git remote.","Initialize the database if the repo never had one: bd init (or restore .beads from git).","Check the dolt CLI is installed and on a supported version; reinstall/upgrade it.","Inspect both wrapped errors: fix the database error (server up, config valid) and validate issues.jsonl line-by-line (jq)."],"exampleFix":"// before\nError: database read failed: config not found; JSONL fallback read failed: open .beads/issues.jsonl: no such file\n// after\n$ bd dolt pull && bd sync\n$ bd doctor","handlingStrategy":"fallback","validationCode":"func beadsReadable(beadsDir string) error {\n    if _, err := os.Stat(filepath.Join(beadsDir, \"issues.jsonl\")); err != nil {\n        return fmt.Errorf(\"issues.jsonl missing: %w\", err)\n    }\n    if err := exec.Command(\"dolt\", \"version\").Run(); err != nil {\n        return fmt.Errorf(\"dolt CLI unavailable: %w\", err)\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":"issues, err := loadMaintenanceIssues(beadsDir)\nif err != nil {\n    // both sources failed; restore from remote then retry once\n    if rerr := restoreFromRemote(); rerr == nil {\n        issues, err = loadMaintenanceIssues(beadsDir)\n    }\n    if err != nil { return err }\n}","preventionTips":["Run bd sync / bd dolt pull regularly so the JSONL export always exists.","Commit .beads/issues.jsonl so fresh clones have a readable source.","Keep the dolt CLI installed and version-compatible.","Validate JSONL with jq after interrupted syncs.","Verify .beads exists at the path before running doctor maintenance."],"tags":["database","dolt","jsonl","fallback"],"backgroundTag":"dual-source-read-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}