What causes "no database connection available (%s)" in gastownhall/beads?

Run `bd init` (or `bd doctor`) in the directory to establish the database

no database connection available (%s)

Error message

no database connection available (%s)

What it means

journalAccessor resolves the active store's EventsJournalAccessor capability for `bd` events journal commands. It first requires a store to exist; when the package-level `store` is nil there is no database connection, so it fails with this message plus a diagnostic hint (diagHint()). It guards both readJournal and pruneJournal.

Source

Thrown at cmd/bd/events.go:314

		return HandleErrorRespectJSON("pruning events journal: %v", err)
	}
	return reportEventsPruned(n, before)
}

func reportEventsPruned(n, before int64) error {
	if jsonOutput {
		return outputJSON(map[string]any{"pruned": n})
	}
	fmt.Printf("Pruned %d events journal record(s) below seq %d\n", n, before)
	return nil
}

// journalAccessor returns the active store's events-journal capability. The
// embedded store and the server-mode store both provide it (via their own
// transaction machinery); a backend that does not is reported as unsupported.
func journalAccessor() (storage.EventsJournalAccessor, error) {
	if store == nil {
		return nil, fmt.Errorf("no database connection available (%s)", diagHint())
	}
	acc, ok := storage.UnwrapStore(store).(storage.EventsJournalAccessor)
	if !ok {
		return nil, fmt.Errorf("storage backend does not support the events journal")
	}
	return acc, nil
}

// readJournal reads records with seq greater than since from the active
// storage seam. Proxied-server mode uses its transaction-bound UOW journal
// capability; direct stores use EventsJournalAccessor.
//
// The projection onto the published envelope is eventsjournal.Records, the same
// one GET /v0/beads/events serves from — see the note on eventsjournal.Record
// for why there is exactly one.
func readJournal(ctx context.Context, since int64, limit int) ([]eventsjournal.Record, error) {
	var rows []storage.EventsJournalRow
	if usesProxiedServer() {

View on GitHub (pinned to 71377f2769)

Solutions

Run `bd init` (or `bd doctor`) in the directory to establish the database
Verify BEADS_DIR / current directory point at the beads repo that contains the database
Follow the diagHint() text printed with the error — it names the connection problem
Remove any --no-db style flags for commands that require store access

Defensive patterns

Strategy: validation

Validate before calling

if _, err := os.Stat(filepath.Join(beadsDir, "db")); err != nil {
    return fmt.Errorf("no beads database in %s; run `bd init` first", beadsDir)
}

Try / catch

if err := readJournalCmd(ctx); err != nil {
    if strings.Contains(err.Error(), "no database connection available") {
        // run `bd init` / `bd doctor`, then retry
    }
}

Prevention

Always initialize the beads database in the working directory before journal commands
Verify BEADS_DIR points at the intended repo
Run `bd doctor` when store-dependent commands fail at startup

When it happens

Trigger: Running a journal command (read/prune path) before any store is opened — e.g. outside a beads-initialized directory, with a failing `bd connect`/init, or in a context where store initialization was skipped (no-db-ops flag, missing database).

Common situations: Running `bd events` in a directory with no .beads database; BEADS_DIR pointing at an empty/wrong location; embedded mode init failed earlier and the error was swallowed.

Related errors

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