gastownhall/beads · error · ErrNoBeadsDatabase

%w. Hint: run 'bd init' to create a database in the current

Error message

%w.
Hint: run 'bd init' to create a database in the current directory

What it means

ensureStoreActiveWithContext locates the .beads directory before opening the storage backend. If beads.FindBeadsDir() finds nothing — no .beads directory in the current directory or any ancestor — it returns ErrNoBeadsDatabase wrapped with a hint to run 'bd init'. Callers distinguish this via errors.Is(err, ErrNoBeadsDatabase): it means 'no workspace at all', not 'workspace broken'.

Source

Thrown at cmd/bd/direct_mode.go:43

	return ensureStoreActiveWithContext(getRootContext())
}

func ensureStoreActiveWithContext(ctx context.Context) error {
	if ctx == nil {
		ctx = context.Background()
	}

	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)

View on GitHub (pinned to 71377f2769)

Solutions

Run 'bd init' in the project root to create the .beads database.
cd into the repository/workspace root (or a subdirectory of it) before running bd commands.
If .beads was deleted, restore it from git or re-init and re-import from issues.jsonl.
Programmatic callers: match with errors.Is(err, ErrNoBeadsDatabase) to handle this case distinctly.

Example fix

// before (wrong directory)
/tmp$ bd list
// after
/tmp/myproject$ bd init && bd list

Defensive patterns

Strategy: validation

Validate before calling

if _, err := os.Stat(".beads"); os.IsNotExist(err) {
    return fmt.Errorf("not a beads workspace: run 'bd init'")
}

Try / catch

if err := ensureStoreActive(); err != nil {
    if errors.Is(err, ErrNoBeadsDatabase) {
        return initWorkspace() // or prompt the user
    }
    return err
}

Prevention

Always run 'bd init' after cloning a project without .beads.
Run bd commands from the repository root or its subdirectories.
Commit .beads/ (or its export) so workspaces are reproducible.
In scripts, match errors.Is(err, ErrNoBeadsDatabase) to auto-init or exit clearly.

When it happens

Trigger: Running any direct-storage bd command (that calls ensureStoreActive) outside a beads workspace: no .beads directory exists in the current directory or any parent, and store is not already active.

Common situations: Running bd in a fresh repo before initialization; running from a directory outside the repo (bd does not cross into the right ancestor); deleted or renamed .beads directory; CI jobs checking out only part of the repo.

Related errors

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