{"record":{"id":"d652249438bcb1c8","repo":"benbjohnson/litestream","slug":"rollback-passive-checkpoint-barrier-w","errorCode":null,"errorMessage":"rollback passive checkpoint barrier: %w","messagePattern":"rollback passive checkpoint barrier: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"db.go","lineNumber":2534,"sourceCode":"\tif exec.state.lastSyncedWALOffset > WALHeaderSize {\n\t\tpreCheckpointFrameN = int((exec.state.lastSyncedWALOffset - WALHeaderSize) / frameSize)\n\t}\n\n\t// Execute checkpoint and immediately issue a write to the WAL to ensure\n\t// a new page is written.\n\tdb.setSyncDiagPhase(diagPhaseCheckpointExec,\n\t\tfunc(s *diagState) {\n\t\t\ts.checkpointMode = mode\n\t\t\ts.lastSyncedWALOffset = exec.state.lastSyncedWALOffset\n\t\t})\n\twalFrameN, err := db.execCheckpoint(ctx, mode)\n\tif err != nil {\n\t\treturn false, err\n\t}\n\n\tif barrierTx != nil {\n\t\tif err = rollback(barrierTx); err != nil {\n\t\t\treturn false, fmt.Errorf(\"rollback passive checkpoint barrier: %w\", err)\n\t\t}\n\t\tbarrierTx = nil\n\t}\n\n\tif err = db.bumpLitestreamSeq(ctx); err != nil {\n\t\treturn false, fmt.Errorf(\"bump litestream seq: %w\", err)\n\t}\n\n\t// If WAL hasn't been restarted, exit.\n\tdb.setSyncDiagPhase(diagPhaseCheckpointVerifyRestart,\n\t\tfunc(s *diagState) {\n\t\t\ts.checkpointMode = mode\n\t\t\ts.lastSyncedWALOffset = exec.state.lastSyncedWALOffset\n\t\t})\n\tother, err := readWALHeader(db.WALPath())\n\tif err != nil {\n\t\treturn false, err\n\t} else if bytes.Equal(hdr, other) {","sourceCodeStart":2516,"sourceCodeEnd":2552,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/db.go#L2516-L2552","documentation":"During a passive checkpoint, Litestream first opened a short 'barrier' transaction, then rolls it back before bumping the litestream sequence number. This error wraps a failure of that rollback call, meaning the barrier transaction could not be cleanly rolled back (e.g. the connection or database is in a bad state). Because the transaction was supposed to be discarded anyway, the wrapped error usually reflects a deeper database/connection problem rather than lost data.","triggerScenarios":"Running the internal passive-checkpoint path (db.checkpoint with CheckpointModePassive, e.g. during regular WAL sync) when rollback(barrierTx) fails: the underlying SQLite connection is busy/corrupt, the db handle was closed concurrently, or the driver returns an error rolling back an already-broken transaction.","commonSituations":"Database file closed or invalidated while a checkpoint is in flight (e.g. calling db.Close() concurrently); SQLite SQLITE_BUSY/IO errors on a slow or failing disk; using the library against a database whose WAL is being manipulated by another process.","solutions":["Check the wrapped inner error (%w) to find the real SQLite failure and fix that first (I/O, busy, closed handle).","Ensure no concurrent db.Close() or another process is checkpointing/truncating the same WAL while Litestream runs.","Retry the sync/checkpoint; a transient SQLITE_BUSY on rollback typically resolves on the next sync cycle.","If the error persists, run 'litestream reset' or integrity_check the database; a corrupt WAL can break transaction teardown."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"if db == nil || db.SyncStatus() == litestream.SyncStatusError { /* recreate/reopen db handle before continuing */ }","typeGuard":null,"tryCatchPattern":"ok, err := dbCheckpoint(ctx, mode)\nif err != nil && strings.Contains(err.Error(), \"rollback passive checkpoint barrier\") {\n    // inspect wrapped cause; log and let next sync retry\n    log.Printf(\"checkpoint barrier rollback failed, will retry: %v\", err)\n}","preventionTips":["Never close the *sql.DB while Litestream replication is active.","Keep only one Litestream instance per database file.","Monitor disk health and free space.","Alert on repeated checkpoint failures rather than ignoring sync errors."],"tags":["sqlite","checkpoint","transaction","rollback"],"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"}