{"record":{"id":"9b4797cf30196ff7","repo":"benbjohnson/litestream","slug":"checkpoint-failed-w","errorCode":null,"errorMessage":"checkpoint failed: %w","messagePattern":"checkpoint failed: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/litestream-test/shrink.go","lineNumber":257,"sourceCode":"\tslog.Debug(\"Deleted rows from table\",\n\t\t\"table\", table,\n\t\t\"rows_deleted\", rowsDeleted,\n\t\t\"duration\", duration,\n\t)\n\n\treturn rowsDeleted, nil\n}\n\nfunc (c *ShrinkCommand) runCheckpoint(db *sql.DB) error {\n\tslog.Info(\"Running checkpoint\", \"mode\", c.CheckpointMode)\n\n\tstartTime := time.Now()\n\tquery := fmt.Sprintf(\"PRAGMA wal_checkpoint(%s)\", c.CheckpointMode)\n\n\tvar busy, written, total int\n\terr := db.QueryRow(query).Scan(&busy, &written, &total)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"checkpoint failed: %w\", err)\n\t}\n\n\tduration := time.Since(startTime)\n\tslog.Info(\"Checkpoint complete\",\n\t\t\"mode\", c.CheckpointMode,\n\t\t\"busy\", busy,\n\t\t\"pages_written\", written,\n\t\t\"total_pages\", total,\n\t\t\"duration\", duration,\n\t)\n\n\treturn nil\n}\n\nfunc (c *ShrinkCommand) runVacuum(db *sql.DB) error {\n\tslog.Info(\"Running VACUUM (this may take a while)\")\n\n\tstartTime := time.Now()","sourceCodeStart":239,"sourceCodeEnd":275,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/cmd/litestream-test/shrink.go#L239-L275","documentation":"This error wraps failure of the `PRAGMA wal_checkpoint(<mode>)` scan in `runCheckpoint`. It means SQLite refused the checkpoint command — the mode string was invalid, the database is not in WAL mode, or the checkpoint could not be executed (e.g. locked by another connection). `shrinkDatabase` calls it after deletes so the WAL is merged before VACUUM.","triggerScenarios":"Invalid `--checkpoint-mode` value (valid: PASSIVE, FULL, RESTART, TRUNCATE); database not opened in WAL mode; another connection blocking the checkpoint (returns busy but scan still succeeds — error here is driver-level failure); corrupted database.","commonSituations":"Typo in the checkpoint mode flag; shrink targeting a journal-mode DELETE database; long-running readers preventing checkpoint completion in conjunction with lock errors.","solutions":["Pass a valid mode: PASSIVE, FULL, RESTART, or TRUNCATE","Verify the DB is in WAL mode: `PRAGMA journal_mode;` — switch with `PRAGMA journal_mode=WAL;`","Close other database connections before checkpointing","Inspect the wrapped `%w` error for the specific SQLite error"],"exampleFix":"// before\nlitestream-test shrink --checkpoint-mode TRUNCATEE\n// after\nlitestream-test shrink --checkpoint-mode TRUNCATE","handlingStrategy":"validation","validationCode":"mode := strings.ToUpper(c.CheckpointMode)\nswitch mode {\ncase \"PASSIVE\", \"FULL\", \"RESTART\", \"TRUNCATE\":\ndefault:\n\treturn fmt.Errorf(\"invalid checkpoint mode %q\", mode)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Validate checkpoint mode against the four valid values","Confirm WAL journal mode with PRAGMA journal_mode","Run checkpoints with no competing connections"],"tags":["sqlite","wal","checkpoint","test-tooling"],"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-14T05:17:10.506Z"}