benbjohnson/litestream · error

cannot verify wal state: %w

Error message

cannot verify wal state: %w

What it means

verifyWithExecutor failed while checking that the WAL has not been overwritten by another process since the last sync (salt/txid verification). A mismatch or read error means the shadow WAL's continuation point can no longer be trusted.

Source

Thrown at db.go:1378

	// This avoids using file size which may include stale frames with old salt
	// values after a checkpoint. See issue #997.
	origWALSize := exec.state.lastSyncedWALOffset
	if origWALSize == 0 {
		// First sync - use file size as fallback
		var err error
		origWALSize, err = db.walFileSize()
		if err != nil {
			return syncResult{}, fmt.Errorf("stat wal before sync: %w", err)
		}
	}

	// 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.

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Ensure only one litestream process replicates a given database
2. If another writer reset the WAL, run 'litestream reset' and re-sync from a fresh snapshot
3. Inspect the wrapped error for the exact verification failure

When it happens

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