{"record":{"id":"9917953ab49f74e3","repo":"benbjohnson/litestream","slug":"checkpoint-w","errorCode":null,"errorMessage":"checkpoint: %w","messagePattern":"checkpoint: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/litestream-test/shrink.go","lineNumber":110,"sourceCode":"\t\t\t\"rows_deleted\", deleted,\n\t\t)\n\t}\n\n\tslog.Info(\"Deletion complete\", \"total_rows_deleted\", totalDeleted)\n\n\tsizeAfterDelete, err := getDatabaseSize(c.DB)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"get size after delete: %w\", err)\n\t}\n\n\tslog.Info(\"Size after deletion\",\n\t\t\"size_mb\", sizeAfterDelete/1024/1024,\n\t\t\"change_mb\", (initialSize-sizeAfterDelete)/1024/1024,\n\t)\n\n\tif c.Checkpoint {\n\t\tif err := c.runCheckpoint(db); err != nil {\n\t\t\treturn fmt.Errorf(\"checkpoint: %w\", err)\n\t\t}\n\n\t\tsizeAfterCheckpoint, _ := getDatabaseSize(c.DB)\n\t\tslog.Info(\"Size after checkpoint\",\n\t\t\t\"size_mb\", sizeAfterCheckpoint/1024/1024,\n\t\t\t\"change_from_delete_mb\", (sizeAfterDelete-sizeAfterCheckpoint)/1024/1024,\n\t\t)\n\t}\n\n\tif c.Vacuum {\n\t\tif err := c.runVacuum(db); err != nil {\n\t\t\treturn fmt.Errorf(\"vacuum: %w\", err)\n\t\t}\n\n\t\tsizeAfterVacuum, _ := getDatabaseSize(c.DB)\n\t\tslog.Info(\"Size after VACUUM\",\n\t\t\t\"size_mb\", sizeAfterVacuum/1024/1024,\n\t\t\t\"total_reduction_mb\", (initialSize-sizeAfterVacuum)/1024/1024,","sourceCodeStart":92,"sourceCodeEnd":128,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/cmd/litestream-test/shrink.go#L92-L128","documentation":"When -checkpoint is passed, shrinkDatabase runs c.runCheckpoint(db), which executes PRAGMA wal_checkpoint(<mode>). Any error is wrapped as `checkpoint: %w`. Checkpointing merges WAL content back into the main database file; it fails when the WAL cannot be processed, most commonly due to concurrent readers/writers or an invalid checkpoint mode string interpolated into the PRAGMA.","triggerScenarios":"Another connection holds read locks so the checkpoint cannot complete (runCheckpoint only errors on SQL failure here, not busy results); c.CheckpointMode contains a value outside PASSIVE/FULL/RESTART/TRUNCATE causing a PRAGMA syntax/argument error; database corruption or I/O error during the checkpoint write.","commonSituations":"Running shrink against a live database while the application or litestream is actively reading; passing -checkpoint-mode=TRUNCATE on a busy system; typo'd mode like 'Pasive'.","solutions":["Use the default PASSIVE mode, or stop other readers/writers before running a FULL/RESTART/TRUNCATE checkpoint","Verify -checkpoint-mode is exactly one of PASSIVE, FULL, RESTART, TRUNCATE","Retry when the database is quiet; check the wrapped inner error for the SQL-level cause","Run `sqlite3 <db> 'PRAGMA wal_checkpoint(PASSIVE);'` manually to reproduce/diagnose"],"exampleFix":"// before\nlitestream-test shrink -db test.db -checkpoint -checkpoint-mode TRUNCATE\n// busy from live readers\n// after\nlitestream-test shrink -db test.db -checkpoint\n# or stop readers first, then use -checkpoint-mode TRUNCATE","handlingStrategy":"try-catch","validationCode":"mode := \"FULL\"\nswitch mode {\ncase \"PASSIVE\", \"FULL\", \"RESTART\", \"TRUNCATE\":\ndefault:\n    return fmt.Errorf(\"invalid checkpoint mode %q\", mode)\n}","typeGuard":null,"tryCatchPattern":"if err := runShrink(args); err != nil {\n    if strings.Contains(err.Error(), \"checkpoint\") {\n        log.Printf(\"checkpoint failed (likely busy readers or bad mode): %v\", err)\n        // retry later or fall back to PASSIVE\n    }\n    return err\n}","preventionTips":["Use PASSIVE mode when other processes may be reading the database","Only pass -checkpoint-mode values from the documented set: PASSIVE, FULL, RESTART, TRUNCATE","Schedule FULL/TRUNCATE checkpoints during quiet periods"],"tags":["sqlite","wal","checkpoint","pragma"],"backgroundTag":"database-query-failed","analyzedSha":"4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3","analyzedAt":"2026-09-06T18:29:25.564Z","contentChangedAt":"2026-09-06T18:29:25.564Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}