gastownhall/beads · error

storage backend does not support the events journal

Error message

storage backend does not support the events journal

What it means

After confirming a store exists, journalAccessor unwraps it via storage.UnwrapStore and type-asserts storage.EventsJournalAccessor. If the concrete backend does not implement the events-journal capability, this error reports the backend as unsupported rather than panicking on a failed assertion. It is a capability gate per backend.

Source

Thrown at cmd/bd/events.go:318

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() {
		if uowProvider == nil {
			return nil, fmt.Errorf("no proxied-server unit-of-work provider available")
		}
		uw, err := uowProvider.NewUOW(ctx)

View on GitHub (pinned to 71377f2769)

Solutions

1. Upgrade beads and the Dolt driver so the backend implements EventsJournalAccessor
2. Check which backend is active (`bd doctor`) and switch to an embedded/Dolt backend that supports the journal
3. If a custom wrapper store is in play, make UnwrapStore able to reach the inner accessor
4. Treat as unsupported-capability: avoid journal subcommands on this backend

// check backend capability up-front
if !backendSupportsEventsJournal(activeBackend) { skipJournalFeatures() }

func supportsEventsJournal(s storage.Store) bool {
    _, ok := storage.UnwrapStore(s).(storage.EventsJournalAccessor)
    return ok
}

if err := journalCmd(ctx); err != nil {
    if strings.Contains(err.Error(), "does not support the events journal") {
        // degrade gracefully: hide journal features for this backend
    }
}

When it happens

Trigger: Using a storage backend (or a wrapper/proxy store that hides the accessor) whose underlying driver does not provide the events journal, then invoking journal commands (`bd events` read or prune).

Common situations: Older beads database/driver version predating the events journal; custom or third-party storage backend; a wrapping store that UnwrapStore cannot see through.

Related errors

• ErrAmbiguousID
• 'bd admin %s' is not yet supported in embedded mode
• cannot use multiple conflict resolution flags
• cannot use both --pull-only and --push-only
• %w (--prefer-local, --prefer-ado, --prefer-newer)

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