{"record":{"id":"1cbd67bb084c913d","repo":"rqlite/rqlite","slug":"checkpointing-wals-w","errorCode":null,"errorMessage":"checkpointing WALs: %w","messagePattern":"checkpointing WALs: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"snapshot/restore.go","lineNumber":101,"sourceCode":"\t\t\t\treturn totalRead, err\n\t\t\t}\n\t\t\twalCR := rsum.NewCRC32Reader(r)\n\t\t\tnr, err := io.CopyN(wf, walCR, int64(wh.SizeBytes))\n\t\t\ttotalRead += nr\n\t\t\tif err != nil {\n\t\t\t\twf.Close()\n\t\t\t\treturn totalRead, fmt.Errorf(\"extracting WAL %d: %w\", i, err)\n\t\t\t}\n\t\t\tif err := wf.Close(); err != nil {\n\t\t\t\treturn totalRead, err\n\t\t\t}\n\t\t\tif got, want := walCR.Sum32(), wh.Crc32; got != want {\n\t\t\t\treturn totalRead, fmt.Errorf(\"CRC32 mismatch for WAL file %d: got %08x, expected %08x\", i, got, want)\n\t\t\t}\n\t\t\twalFiles = append(walFiles, walPath)\n\t\t}\n\t\tif err := db.ReplayWAL(dstPath, walFiles, false); err != nil {\n\t\t\treturn totalRead, fmt.Errorf(\"checkpointing WALs: %w\", err)\n\t\t}\n\t\tfor _, wf := range walFiles {\n\t\t\tos.Remove(wf)\n\t\t}\n\t}\n\n\treturn totalRead, nil\n}\n","sourceCodeStart":83,"sourceCodeEnd":110,"githubUrl":"https://github.com/rqlite/rqlite/blob/7586a4d1bdbd9a5a80021664c5a863cd850adb60/snapshot/restore.go#L83-L110","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use a complete snapshot produced atomically by the same node (DB and WALs together)","Retry the restore after freeing disk space and confirming storage health","Restore from a fresh snapshot or from a /boot restore instead of mixing parts","Inspect the wrapped error from ReplayWAL for the specific sqlite failure"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Confirm DB and WALs come from the same snapshot archive before calling Restore.\nif !sameSnapshotArchive(dbPart, walPart) { return errors.New(\"mismatched DB/WAL snapshot parts\") }","typeGuard":null,"tryCatchPattern":"if _, err := snap.Restore(dir, r); err != nil {\n    if strings.Contains(err.Error(), \"checkpointing WALs\") {\n        // fall back to a fresh full snapshot or /boot restore\n    }\n    return err\n}","preventionTips":["Always use DB and WAL files from one atomic snapshot","Ensure ample free disk space for replay writes","Prefer fresh full snapshots over hand-assembled archives","Test restores regularly so replay failures surface early"],"tags":["wal","checkpoint","snapshot","corruption"],"backgroundTag":"wal-replay-failed","analyzedSha":"7586a4d1bdbd9a5a80021664c5a863cd850adb60","analyzedAt":"2026-09-03T07:03:02.260Z","contentChangedAt":"2026-09-03T07:03:02.260Z","schemaVersion":2},"datasetVersion":"2026-09-10T12:17:11.382Z"}