rqlite/rqlite · critical

checkpointing WALs: %w

Error message

checkpointing WALs: %w

What it means

After all WAL files pass CRC verification, Restore replays them into the restored database via db.ReplayWAL to checkpoint them. This error wraps any failure from that replay step, meaning the valid-looking WALs could not be applied to the database file.

Source

Thrown at snapshot/restore.go:101

				return totalRead, err
			}
			walCR := rsum.NewCRC32Reader(r)
			nr, err := io.CopyN(wf, walCR, int64(wh.SizeBytes))
			totalRead += nr
			if err != nil {
				wf.Close()
				return totalRead, fmt.Errorf("extracting WAL %d: %w", i, err)
			}
			if err := wf.Close(); err != nil {
				return totalRead, err
			}
			if got, want := walCR.Sum32(), wh.Crc32; got != want {
				return totalRead, fmt.Errorf("CRC32 mismatch for WAL file %d: got %08x, expected %08x", i, got, want)
			}
			walFiles = append(walFiles, walPath)
		}
		if err := db.ReplayWAL(dstPath, walFiles, false); err != nil {
			return totalRead, fmt.Errorf("checkpointing WALs: %w", err)
		}
		for _, wf := range walFiles {
			os.Remove(wf)
		}
	}

	return totalRead, nil
}

View on GitHub (pinned to 7586a4d1bd)

Solutions

1. Use a complete snapshot produced atomically by the same node (DB and WALs together)
2. Retry the restore after freeing disk space and confirming storage health
3. Restore from a fresh snapshot or from a /boot restore instead of mixing parts
4. Inspect the wrapped error from ReplayWAL for the specific sqlite failure

// Confirm DB and WALs come from the same snapshot archive before calling Restore.
if !sameSnapshotArchive(dbPart, walPart) { return errors.New("mismatched DB/WAL snapshot parts") }

if _, err := snap.Restore(dir, r); err != nil {
    if strings.Contains(err.Error(), "checkpointing WALs") {
        // fall back to a fresh full snapshot or /boot restore
    }
    return err
}

When it happens

Trigger: snapshot.Restore() calls db.ReplayWAL(dstPath, walFiles, false) and it returns an error — e.g. WAL pages don't fit the DB, sqlite recover fails, or file-level I/O problems during checkpointing.

Common situations: Restoring a snapshot whose DB and WALs came from mismatched sources (mixed snapshot parts); restoring onto a filesystem that cannot handle the write load (full disk); manually assembled snapshot archives with inconsistent contents.

Related errors

• read WAL salt: %w
• create compacting frame scanner: %w
• invalid wal header magic: %x
• checkpoint leftover WAL: %w
• moving WAL %s: %w

AI-assisted analysis of rqlite/rqlite@7586a4d1bd (2026-09-03). Data as JSON: /api/errors/1cbd67bb084c913d. Report an issue: GitHub.