benbjohnson/litestream · error

stat wal before sync: %w

Error message

stat wal before sync: %w

What it means

On the first sync (last synced offset is 0), verifyAndSyncWithExecutor fell back to os.Stat on the WAL file and it failed. The WAL file is missing or unreadable at the moment sync begins — e.g. the database was deleted underneath Litestream.

Source

Thrown at db.go:1368

	}, 0)
}

func (db *DB) verifyAndSyncWithExecutor(ctx context.Context, checkpointing bool, exec *syncExecutor, maxSyncWALBytes int64) (syncResult, error) {
	db.setSyncDiagPhase(diagPhaseStatWAL, func(s *diagState) {
		s.txID = exec.pos.TXID + 1
		s.lastSyncedWALOffset = exec.state.lastSyncedWALOffset
	})

	// Use the last synced WAL offset as the logical size for checkpoint decisions.
	// 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
	})

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Verify the database and -wal files still exist and are readable
2. Restart litestream if the database was just recreated

When it happens

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