benbjohnson/litestream · error

db required

Error message

db required

What it means

Store.RegisterDB validates that the supplied *DB pointer is non-nil and returns this error immediately otherwise. Registering a nil DB would panic later when the store iterates or opens it, so the guard converts the misuse into an explicit error. It is a programming error in the caller, not a runtime state issue.

Source

Thrown at store.go:292

	}

	// Cancel and wait for background tasks to complete.
	s.cancel()
	s.wg.Wait()

	return err
}

func (s *Store) DBs() []*DB {
	s.mu.Lock()
	defer s.mu.Unlock()
	return slices.Clone(s.dbs)
}

// RegisterDB registers a new database with the store and starts monitoring it.
func (s *Store) RegisterDB(db *DB) error {
	if db == nil {
		return fmt.Errorf("db required")
	}

	// First check: see if database already exists
	s.mu.Lock()
	for _, existing := range s.dbs {
		if existing.Path() == db.Path() {
			s.mu.Unlock()
			return nil
		}
	}
	s.mu.Unlock()

	// Apply store-wide settings before opening the database.
	db.SetLogger(s.Logger.With(LogKeyDB, filepath.Base(db.Path())))
	db.L0Retention = s.L0Retention
	db.ShutdownSyncTimeout = s.ShutdownSyncTimeout
	db.ShutdownSyncInterval = s.ShutdownSyncInterval
	db.VerifyCompaction = s.VerifyCompaction

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Ensure the *DB returned by the DB constructor is non-nil before calling RegisterDB
2. Check the constructor's error return; fix the earlier failure that yielded a nil DB
3. Add a nil check at the call site as a defensive guard

Example fix

// before
var db *litestream.DB
store.RegisterDB(db) // "db required"

// after
db, err := litestream.NewDB(path)
if err != nil {
    return err
}
if db == nil {
    return fmt.Errorf("db construction returned nil")
}
return store.RegisterDB(db)

if db == nil {
    return fmt.Errorf("cannot register nil DB")
}

func dbReady(db *litestream.DB) bool { return db != nil }

if err := store.RegisterDB(db); err != nil && err.Error() == "db required" {
    // caller bug: nil DB; fix initialization, do not retry
}

When it happens

Trigger: Calling store.RegisterDB(nil) directly, or code paths that construct a *DB which failed and left the variable nil before registration (e.g. NewDB returned nil on an earlier error that was ignored).

Common situations: Custom integrations or scripts driving the litestream library API that skip checking the error from DB construction; refactors that reorder initialization so registration happens before db assignment.

Related errors

• db path required
• store required
• snapshot interval must be greater than 0
• snapshot retention must be greater than 0
• compaction interval must be greater than 0

AI-assisted analysis of benbjohnson/litestream@4ed7a308f6 (2026-09-06). Data as JSON: /api/errors/c261f83d0dd45678. Report an issue: GitHub.