What causes "minimum checkpoint page count required" in benbjohnson/litestream?

Set db.MinCheckpointPageN = litestream.DefaultMinCheckpointPageN (the library's default, typically 1000).

minimum checkpoint page count required

Error message

minimum checkpoint page count required

What it means

DB.Open requires db.MinCheckpointPageN to be strictly positive. This value is the WAL page-count threshold that triggers passive checkpoints, and a zero or negative value would make the checkpoint loop never fire (or behave nonsensically). It is part of the same open-time field validation block.

Source

Thrown at db.go:788

func (db *DB) Open() (err error) {
	db.mu.Lock()
	if db.opened {
		db.mu.Unlock()
		return nil // already open
	}
	// Recreate context for fresh start (handles reopen after close)
	db.ctx, db.cancel = context.WithCancel(context.Background())
	db.mu.Unlock()

	// Validate fields on database.
	if db.Replica == nil {
		return fmt.Errorf("replica required before opening database")
	}
	if db.Replica.Client == nil {
		return fmt.Errorf("replica client required before opening database")
	}
	if db.MinCheckpointPageN <= 0 {
		return fmt.Errorf("minimum checkpoint page count required")
	}

	// Clear old temporary files that my have been left from a crash.
	if err := removeTmpFiles(db.metaPath); err != nil {
		return fmt.Errorf("cannot remove tmp files: %w", err)
	}

	// Set the compactor client once before starting any goroutines.
	db.compactor.VerifyCompaction = db.VerifyCompaction
	db.compactor.RetentionEnabled = db.RetentionEnabled
	db.compactor.client = db.Replica.Client

	// Start monitoring SQLite database in a separate goroutine.
	if db.MonitorInterval > 0 {
		db.wg.Add(1)
		go func() { defer db.wg.Done(); db.monitor() }()
	}

View on GitHub (pinned to 4ed7a308f6)

Solutions

Set db.MinCheckpointPageN = litestream.DefaultMinCheckpointPageN (the library's default, typically 1000).
Choose a sensible positive page count appropriate for your write volume before Open().
Prefer constructing databases through the config loader, which fills in defaults.

Example fix

// before
db := litestream.NewDB("/data/app.db")
if err := db.Open(); err != nil { ... }
// after
db := litestream.NewDB("/data/app.db")
db.MinCheckpointPageN = litestream.DefaultMinCheckpointPageN
if err := db.Open(); err != nil { ... }

Defensive patterns

Strategy: validation

Validate before calling

if db.MinCheckpointPageN <= 0 {
    db.MinCheckpointPageN = litestream.DefaultMinCheckpointPageN
}

Prevention

Never hand-build DB structs without defaults; use NewDB plus explicit defaults.
Review struct literals for omitted zero-value fields.

When it happens

Trigger: Instantiating a DB via the library API and leaving MinCheckpointPageN at its zero value; explicitly setting it to 0 or a negative number in custom construction code.

Common situations: Programmatic users of litestream as a library who build DB structs by hand (the CLI default config path sets this automatically); copy-pasted struct literal initialization omitting the field.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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