{"record":{"id":"e31f7ea4fc068c8f","repo":"benbjohnson/litestream","slug":"bump-litestream-seq-w","errorCode":null,"errorMessage":"bump litestream seq: %w","messagePattern":"bump litestream seq: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"db.go","lineNumber":2540,"sourceCode":"\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) {\n\t\texec.state.syncedSinceCheckpoint = false\n\t\treturn false, nil\n\t}\n\texec.state.truncatePassiveFailed = false\n\n\tif mode == CheckpointModePassive {","sourceCodeStart":2522,"sourceCodeEnd":2558,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/db.go#L2522-L2558","documentation":"After a passive checkpoint completes and the barrier transaction is released, Litestream bumps an internal sequence number (bumpLitestreamSeq) used to track replication progress. If that update fails, this error is returned and the checkpoint reports failure. It indicates Litestream could not write its bookkeeping state to the SQLite database.","triggerScenarios":"db.bumpLitestreamSeq(ctx) returning an error during the checkpoint flow: the database is read-only, the disk is full, the table/sequence state is locked by another transaction, or the underlying UPDATE fails with SQLITE_BUSY/SQLITE_READONLY.","commonSituations":"Read-only filesystem or read-only SQLite connection after failover; another Litestream replica process competing on the same database; disk-full conditions on the host.","solutions":["Inspect the wrapped error: SQLITE_READONLY/SQLITE_BUSY/disk I/O each has a distinct remedy (permissions, contention, disk space).","Verify only one Litestream process replicates the database (use the lease feature) to avoid write contention.","Check filesystem is writable and has free space for the WAL and lock updates.","Retry; the next sync cycle will bump the sequence again if the failure was transient."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"if fi, err := os.Stat(dbPath); err != nil || fi.Mode().Perm()&0200 == 0 { return fmt.Errorf(\"database not writable: %s\", dbPath) }","typeGuard":null,"tryCatchPattern":"if err := syncOnce(ctx); err != nil && strings.Contains(err.Error(), \"bump litestream seq\") {\n    switch {\n    case errors.Is(err, sqlite.ErrBusy): retryWithBackoff()\n    case errors.Is(err, sqlite.ErrReadonly): alertReadOnlyFilesystem()\n    }\n}","preventionTips":["Ensure the SQLite file, WAL, and directory are writable by the Litestream user.","Prevent read-only mounts after failover from being replicated against.","Use replica leasing to avoid two Litestream processes on one database.","Monitor disk usage; full disks break bookkeeping writes."],"tags":["sqlite","checkpoint","sequence","write-failed"],"backgroundTag":"database-write-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"}