benbjohnson/litestream · error

checkpoint: %w

Error message

checkpoint: %w

What it means

The WAL checkpoint performed after a sync (checkpointIfNeeded) failed. Checkpointing truncates the WAL after it is fully replicated; failure is usually a busy/locked database, a SQLite I/O error, or a poisoned WAL state.

Source

Thrown at db.go:1320

	}
	exec.applySyncResult(result)

	// Track that data was synced for time-based checkpoint decisions.
	if result.synced {
		exec.state.syncedSinceCheckpoint = true
	}

	// Checkpoint checks normally wait until the WAL is fully synced, but the
	// emergency truncate threshold must be honored even mid catch-up:
	// sustained writes could otherwise keep every chunk limited and defer the
	// truncate checkpoint indefinitely, growing the WAL without bound.
	if !result.limited || result.syncedToWALEnd || db.exceedsTruncateThreshold(result.origWALSize) {
		db.setSyncDiagPhase(diagPhaseCheckpointIfNeeded, func(s *diagState) {
			s.txID = exec.pos.TXID
			s.lastSyncedWALOffset = exec.state.lastSyncedWALOffset
		})
		if err := db.checkpointIfNeeded(ctx, exec, result.origWALSize, result.newWALSize); err != nil {
			return result, fmt.Errorf("checkpoint: %w", err)
		}
	}

	db.setSyncDiagPhase(diagPhaseUpdateMetrics, func(s *diagState) {
		s.txID = exec.pos.TXID
		s.lastSyncedWALOffset = exec.state.lastSyncedWALOffset
	})

	// Compute current index and total shadow WAL size.
	db.txIDGauge.Set(float64(exec.pos.TXID))

	// Update file size metrics.
	if fi, err := os.Stat(db.path); err == nil {
		db.dbSizeGauge.Set(float64(fi.Size()))
	}
	db.walSizeGauge.Set(float64(exec.state.lastSyncedWALOffset))

	return result, nil

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Check whether another process holds a lock on the database
2. Verify disk space and file permissions on db/-wal
3. Inspect the wrapped SQLite error; consider 'litestream reset' if local LTX state is corrupted

When it happens

Trigger: Thrown at db.go:1320 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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