benbjohnson/litestream · error

sync: %w

Error message

sync: %w

What it means

The core shadow-WAL sync step (db.sync) failed after WAL state verification. The wrapped error comes from reading WAL frames and writing LTX files; typical causes are local disk errors, meta-directory problems, or replica client upload failures.

Source

Thrown at db.go:1389

	// Verify our last sync matches the current state of the WAL.
	// This ensures that the last sync position of the real WAL hasn't
	// been overwritten by another process.
	db.setSyncDiagPhase(diagPhaseVerify)
	info, err := db.verifyWithExecutor(ctx, exec)
	if err != nil {
		return syncResult{}, fmt.Errorf("cannot verify wal state: %w", err)
	}

	db.setSyncDiagPhase(diagPhaseSyncLTX, func(s *diagState) {
		s.txID = exec.pos.TXID + 1
		s.snapshotting = info.snapshotting
		s.reason = info.reason
		s.lastSyncedWALOffset = exec.state.lastSyncedWALOffset
	})
	result, err := db.sync(ctx, checkpointing, exec, info, maxSyncWALBytes)
	if err != nil {
		return syncResult{}, fmt.Errorf("sync: %w", err)
	}

	result.origWALSize = origWALSize
	return result, nil
}

// checkpointIfNeeded performs a checkpoint based on configured thresholds.
// Checks thresholds in priority order: TruncatePageN → MinCheckpointPageN → CheckpointInterval.
//
// TruncatePageN uses TRUNCATE mode (blocking). Others use PASSIVE mode, which
// briefly holds the write lock to seal the WAL and can be skipped when the
// database is busy.
//
// Time-based checkpoints only trigger if exec.state.syncedSinceCheckpoint is true, indicating
// that data has been synced since the last checkpoint. This prevents creating unnecessary
// LTX files when the only WAL data is from internal bookkeeping (like _litestream_seq
// updates from previous checkpoints). See issue #896.
func (db *DB) checkpointIfNeeded(ctx context.Context, exec *syncExecutor, origWALSize, newWALSize int64) error {

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Inspect the wrapped error for the failing subsystem
2. Check disk space and permissions on the meta directory
3. Verify replica backend health; sync is retried on the next interval

When it happens

Trigger: Thrown at db.go:1389 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/c496dd9974b069e3. Report an issue: GitHub.