{"record":{"id":"c496dd9974b069e3","repo":"benbjohnson/litestream","slug":"sync-w","errorCode":null,"errorMessage":"sync: %w","messagePattern":"sync: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"db.go","lineNumber":1389,"sourceCode":"\n\t// Verify our last sync matches the current state of the WAL.\n\t// This ensures that the last sync position of the real WAL hasn't\n\t// been overwritten by another process.\n\tdb.setSyncDiagPhase(diagPhaseVerify)\n\tinfo, err := db.verifyWithExecutor(ctx, exec)\n\tif err != nil {\n\t\treturn syncResult{}, fmt.Errorf(\"cannot verify wal state: %w\", err)\n\t}\n\n\tdb.setSyncDiagPhase(diagPhaseSyncLTX, func(s *diagState) {\n\t\ts.txID = exec.pos.TXID + 1\n\t\ts.snapshotting = info.snapshotting\n\t\ts.reason = info.reason\n\t\ts.lastSyncedWALOffset = exec.state.lastSyncedWALOffset\n\t})\n\tresult, err := db.sync(ctx, checkpointing, exec, info, maxSyncWALBytes)\n\tif err != nil {\n\t\treturn syncResult{}, fmt.Errorf(\"sync: %w\", err)\n\t}\n\n\tresult.origWALSize = origWALSize\n\treturn result, nil\n}\n\n// checkpointIfNeeded performs a checkpoint based on configured thresholds.\n// Checks thresholds in priority order: TruncatePageN → MinCheckpointPageN → CheckpointInterval.\n//\n// TruncatePageN uses TRUNCATE mode (blocking). Others use PASSIVE mode, which\n// briefly holds the write lock to seal the WAL and can be skipped when the\n// database is busy.\n//\n// Time-based checkpoints only trigger if exec.state.syncedSinceCheckpoint is true, indicating\n// that data has been synced since the last checkpoint. This prevents creating unnecessary\n// LTX files when the only WAL data is from internal bookkeeping (like _litestream_seq\n// updates from previous checkpoints). See issue #896.\nfunc (db *DB) checkpointIfNeeded(ctx context.Context, exec *syncExecutor, origWALSize, newWALSize int64) error {","sourceCodeStart":1371,"sourceCodeEnd":1407,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/db.go#L1371-L1407","documentation":"The core shadow-WAL sync step (db.sync) failed after WAL state verification. The wrapped error comes from reading WAL frames and writing LTX files; typical causes are local disk errors, meta-directory problems, or replica client upload failures.","triggerScenarios":"Thrown at db.go:1389 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Inspect the wrapped error for the failing subsystem","Check disk space and permissions on the meta directory","Verify replica backend health; sync is retried on the next interval"],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"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"}