benbjohnson/litestream · error

bump litestream seq: %w

Error message

bump litestream seq: %w

What it means

After a passive checkpoint completes and the barrier transaction is released, Litestream bumps an internal sequence number (bumpLitestreamSeq) used to track replication progress. If that update fails, this error is returned and the checkpoint reports failure. It indicates Litestream could not write its bookkeeping state to the SQLite database.

Source

Thrown at db.go:2540

	db.setSyncDiagPhase(diagPhaseCheckpointExec,
		func(s *diagState) {
			s.checkpointMode = mode
			s.lastSyncedWALOffset = exec.state.lastSyncedWALOffset
		})
	walFrameN, err := db.execCheckpoint(ctx, mode)
	if err != nil {
		return false, err
	}

	if barrierTx != nil {
		if err = rollback(barrierTx); err != nil {
			return false, fmt.Errorf("rollback passive checkpoint barrier: %w", err)
		}
		barrierTx = nil
	}

	if err = db.bumpLitestreamSeq(ctx); err != nil {
		return false, fmt.Errorf("bump litestream seq: %w", err)
	}

	// If WAL hasn't been restarted, exit.
	db.setSyncDiagPhase(diagPhaseCheckpointVerifyRestart,
		func(s *diagState) {
			s.checkpointMode = mode
			s.lastSyncedWALOffset = exec.state.lastSyncedWALOffset
		})
	other, err := readWALHeader(db.WALPath())
	if err != nil {
		return false, err
	} else if bytes.Equal(hdr, other) {
		exec.state.syncedSinceCheckpoint = false
		return false, nil
	}
	exec.state.truncatePassiveFailed = false

	if mode == CheckpointModePassive {

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Inspect the wrapped error: SQLITE_READONLY/SQLITE_BUSY/disk I/O each has a distinct remedy (permissions, contention, disk space).
2. Verify only one Litestream process replicates the database (use the lease feature) to avoid write contention.
3. Check filesystem is writable and has free space for the WAL and lock updates.
4. Retry; the next sync cycle will bump the sequence again if the failure was transient.

if fi, err := os.Stat(dbPath); err != nil || fi.Mode().Perm()&0200 == 0 { return fmt.Errorf("database not writable: %s", dbPath) }

if err := syncOnce(ctx); err != nil && strings.Contains(err.Error(), "bump litestream seq") {
    switch {
    case errors.Is(err, sqlite.ErrBusy): retryWithBackoff()
    case errors.Is(err, sqlite.ErrReadonly): alertReadOnlyFilesystem()
    }
}

When it happens

Trigger: db.bumpLitestreamSeq(ctx) returning an error during the checkpoint flow: the database is read-only, the disk is full, the table/sequence state is locked by another transaction, or the underlying UPDATE fails with SQLITE_BUSY/SQLITE_READONLY.

Common situations: Read-only filesystem or read-only SQLite connection after failover; another Litestream replica process competing on the same database; disk-full conditions on the host.

Related errors

• checkpoint: %w
• checkpoint failed: %w
• begin passive checkpoint barrier: %w
• _litestream_lock: %w
• rollback passive checkpoint barrier: %w

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