What causes "failed to open database: %w Hint: %s" in gastownhall/beads?

Read the wrapped cause and the diagHint() text; run 'bd doctor' for a store-free diagnosis.

failed to open database: %w Hint: %s

Error message

failed to open database: %w
Hint: %s

What it means

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.

Source

Thrown at cmd/bd/direct_mode.go:51

	lockStore()
	active := isStoreActive() && getStore() != nil
	unlockStore()
	if active {
		return nil
	}

	// Find the .beads directory
	beadsDir := beads.FindBeadsDir()
	if beadsDir == "" {
		return fmt.Errorf("%w.\n"+
			"Hint: run 'bd init' to create a database in the current directory", ErrNoBeadsDatabase)
	}

	// Use the factory to create the appropriate backend
	// based on metadata.json configuration and build tags
	store, err := newDoltStoreFromConfig(ctx, beadsDir)
	if err != nil {
		return fmt.Errorf("failed to open database: %w\nHint: %s", err, diagHint())
	}

	// Update the database path for compatibility with code that expects it
	if dbPath := beads.FindDatabasePath(); dbPath != "" {
		setDBPath(dbPath)
	}

	lockStore()
	setStore(store)
	setStoreActive(true)
	unlockStore()

	return nil
}

View on GitHub (pinned to 71377f2769)

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.

Example fix

// check backend config matches binary
cat .beads/metadata.json
// rebuild with the right backend if needed
go build -tags dolt ./cmd/bd

Defensive patterns

Strategy: try-catch

Validate before calling

// probe metadata and DB presence before opening
if _, err := os.Stat(filepath.Join(beadsDir, "metadata.json")); err != nil {
    return fmt.Errorf("metadata.json missing: %w", err)
}

Try / catch

if err := ensureStoreActive(); err != nil {
    var inner error
    if errors.As(err, &inner) || strings.Contains(err.Error(), "failed to open database") {
        return runDoctorRepair() // 'bd doctor' is a store-free repair path
    }
    return err
}

Prevention

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.

When it happens

Trigger: 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.

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

Related errors

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