gastownhall/beads · critical

database read failed: %w; JSONL fallback read failed: %v

Error message

database read failed: %w; JSONL fallback read failed: %v

What it means

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.

Source

Thrown at cmd/bd/doctor/maintenance.go:520

}

// loadMaintenanceIssues loads issues for maintenance checks.
// It prefers Dolt (source of truth) and falls back to legacy JSONL for
// backwards compatibility with non-Dolt installations.
func loadMaintenanceIssues(path string) ([]*types.Issue, error) {
	beadsDir := ResolveBeadsDirForRepo(path)

	issues, err := loadMaintenanceIssuesFromDatabase(beadsDir)
	if err == nil {
		return issues, nil
	}

	issues, jsonlErr := loadMaintenanceIssuesFromJSONL(beadsDir)
	if jsonlErr == nil {
		return issues, nil
	}

	return nil, fmt.Errorf("database read failed: %w; JSONL fallback read failed: %v", err, jsonlErr)
}

func loadMaintenanceIssuesFromDatabase(beadsDir string) ([]*types.Issue, error) {
	ctx := context.Background()
	store, err := dolt.NewFromConfigWithCLIOptions(ctx, beadsDir, &dolt.Config{ReadOnly: true})
	if err != nil {
		return nil, err
	}
	defer func() { _ = store.Close() }()

	ephemeral := false
	return store.SearchIssues(ctx, "", types.IssueFilter{Ephemeral: &ephemeral})
}

func loadMaintenanceIssuesFromJSONL(beadsDir string) ([]*types.Issue, error) {
	jsonlPath := filepath.Join(beadsDir, "issues.jsonl")
	file, err := os.Open(jsonlPath) // #nosec G304 - path constructed safely
	if err != nil {

View on GitHub (pinned to 71377f2769)

Solutions

  1. Run bd dolt pull / bd sync to restore the JSONL export or database from the git remote.
  2. Initialize the database if the repo never had one: bd init (or restore .beads from git).
  3. Check the dolt CLI is installed and on a supported version; reinstall/upgrade it.
  4. Inspect both wrapped errors: fix the database error (server up, config valid) and validate issues.jsonl line-by-line (jq).

Example fix

// before
Error: database read failed: config not found; JSONL fallback read failed: open .beads/issues.jsonl: no such file
// after
$ bd dolt pull && bd sync
$ bd doctor
Defensive patterns

Strategy: fallback

Validate before calling

func beadsReadable(beadsDir string) error {
    if _, err := os.Stat(filepath.Join(beadsDir, "issues.jsonl")); err != nil {
        return fmt.Errorf("issues.jsonl missing: %w", err)
    }
    if err := exec.Command("dolt", "version").Run(); err != nil {
        return fmt.Errorf("dolt CLI unavailable: %w", err)
    }
    return nil
}

Try / catch

issues, err := loadMaintenanceIssues(beadsDir)
if err != nil {
    // both sources failed; restore from remote then retry once
    if rerr := restoreFromRemote(); rerr == nil {
        issues, err = loadMaintenanceIssues(beadsDir)
    }
    if err != nil { return err }
}

Prevention

When it happens

Trigger: loadMaintenanceIssuesFromDatabase fails (dolt store cannot open/config) AND loadMaintenanceIssuesFromJSONL also fails (missing/corrupt/unparseable issues.jsonl).

Common situations: 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.

Related errors

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/a461aab560535be8. Report an issue: GitHub.