gastownhall/beads · critical

failed to initialize database: %w

Error message

failed to initialize database: %w

What it means

After deleting the old database in option [2], the fix re-creates it in-process via `dolt.NewFromConfig(ctx, beadsDir)`, which initializes a fresh Dolt store and auto-bootstraps issues from `.beads/issues.jsonl`. If store creation or bootstrap fails, the error is wrapped as `failed to initialize database: %w`. At this point the old database is already removed, so recovery depends on the JSONL export.

Source

Thrown at cmd/bd/doctor/fix/repo_fingerprint.go:175

		fmt.Printf("  → Removing %s...\n", dbPath)
		if isDolt {
			if err := os.RemoveAll(dbPath); err != nil && !os.IsNotExist(err) {
				return fmt.Errorf("failed to remove Dolt database: %w", err)
			}
		} else {
			if err := os.Remove(dbPath); err != nil && !os.IsNotExist(err) {
				return fmt.Errorf("failed to remove database: %w", err)
			}
			_ = os.Remove(dbPath + "-wal")
			_ = os.Remove(dbPath + "-shm")
		}

		// Reinitialize by creating a new store (auto-bootstraps from JSONL)
		fmt.Println("  → Reinitializing database from JSONL...")
		ctx := context.Background()
		store, err := dolt.NewFromConfig(ctx, beadsDir)
		if err != nil {
			return fmt.Errorf("failed to initialize database: %w", err)
		}
		defer func() { _ = store.Close() }()

		fmt.Println("  ✓ Database reinitialized")
		return nil

	case "s", "":
		fmt.Println("  → Skipped")
		return nil

	default:
		fmt.Printf("  → Unrecognized input '%s', skipping\n", response)
		return nil
	}
}

View on GitHub (pinned to 71377f2769)

Solutions

  1. Check `.beads/issues.jsonl` exists and is valid JSONL — it is the bootstrap source for the new database.
  2. Free disk space and ensure `.beads` is writable, then re-run the fix (or any bd command that re-initializes the store).
  3. Inspect the wrapped error from `dolt.NewFromConfig` for the precise cause (config parse, IO, bootstrap) and fix accordingly.
  4. If the JSONL is stale, restore the database from git history or a Dolt remote (`bd dolt pull`) instead of reinitializing.

Example fix

# before: stale/missing export leaves an empty or failing reinit
ls .beads/issues.jsonl   # missing or truncated
# after: restore the export from git, then retry
git checkout -- .beads/issues.jsonl
bd doctor --fix --yes
Defensive patterns

Strategy: fallback

Validate before calling

jsonl := filepath.Join(beadsDir, "issues.jsonl")
info, err := os.Stat(jsonl)
if err != nil {
	return fmt.Errorf("bootstrap export missing: %w", err)
}
if info.Size() == 0 {
	return errors.New("issues.jsonl is empty; restore from git or dolt remote before reinit")
}
if avail := freeDisk(beadsDir); avail < 64*1024*1024 {
	return errors.New("insufficient disk space for reinitialization")
}

Try / catch

if err := fix.RepoFingerprint(path, true); err != nil && strings.Contains(err.Error(), "failed to initialize database") {
	// old DB is gone; recover from export or remote
	_ = exec.Command("git", "checkout", "--", ".beads/issues.jsonl").Run()
	_ = exec.Command("bd", "dolt", "pull").Run()
	// retry initialization before giving up
	if err2 := fix.RepoFingerprint(path, true); err2 != nil {
		log.Fatalf("reinit failed after recovery attempt: %v", err2)
	}
}

Prevention

When it happens

Trigger: `dolt.NewFromConfig` fails right after the old DB was deleted: corrupt or missing `.beads/issues.jsonl` to bootstrap from, `.beads` not writable, disk full, corrupted Dolt config in `.beads`, or leftover Dolt metadata/locks confusing initialization.

Common situations: User deleted the database with a stale or never-synced issues.jsonl (data loss risk); .beads directory made read-only mid-flow; interrupted previous init leaving partial Dolt files; out-of-disk during re-initialization.

Related errors

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