{"record":{"id":"ae45b1ab8ea91052","repo":"benbjohnson/litestream","slug":"db-sync-w","errorCode":null,"errorMessage":"db sync: %w","messagePattern":"db sync: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"db.go","lineNumber":722,"sourceCode":"\t\treturn SyncStatus{}, fmt.Errorf(\"remote position: %w\", err)\n\t}\n\n\treturn SyncStatus{\n\t\tLocalTXID:  localPos.TXID,\n\t\tRemoteTXID: remotePos.TXID,\n\t\tInSync:     localPos.TXID > 0 && localPos.TXID == remotePos.TXID,\n\t}, nil\n}\n\n// SyncAndWait performs a full sync: WAL to LTX files, then LTX files to remote\n// replica. Blocks until both stages complete.\nfunc (db *DB) SyncAndWait(ctx context.Context) error {\n\tif db.Replica == nil {\n\t\treturn fmt.Errorf(\"no replica configured\")\n\t}\n\n\tif err := db.Sync(ctx); err != nil {\n\t\treturn fmt.Errorf(\"db sync: %w\", err)\n\t}\n\tif err := db.Replica.Sync(ctx); err != nil {\n\t\treturn fmt.Errorf(\"replica sync: %w\", err)\n\t}\n\treturn nil\n}\n\n// EnsureExists restores the database from the configured replica if the local\n// database file does not exist. If no backup is available, it returns nil and\n// a fresh database will be created on Open(). Must be called before Open().\nfunc (db *DB) EnsureExists(ctx context.Context) error {\n\tif db.Replica == nil {\n\t\treturn fmt.Errorf(\"no replica configured\")\n\t}\n\tif db.Replica.Client == nil {\n\t\treturn fmt.Errorf(\"no replica client configured\")\n\t}\n","sourceCodeStart":704,"sourceCodeEnd":740,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/db.go#L704-L740","documentation":"DB.SyncAndWait() wraps an error from the first stage, db.Sync(ctx), with \"db sync\". db.Sync rolls the local WAL into LTX files locally; a failure here means the local checkpoint/compaction step failed — replication never started. The root cause is chained via %w.","triggerScenarios":"Calling db.SyncAndWait(ctx) when db.Sync fails: SQLite checkpoint errors, WAL read errors, failure writing local LTX files, or the DB not being open/initialized.","commonSituations":"Corrupted WAL after a crash; disk full while writing LTX files; another process holding SQLite locks preventing checkpointing; calling SyncAndWait before Open().","solutions":["Unwrap the error to see the underlying SQLite/LTX failure.","Verify the DB is open (Open() called) and the data directory has writable space.","Check for competing SQLite writers/locks on the database.","If local LTX state is corrupted, use `litestream reset` / auto-recover to clear it, then re-sync."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"if _, err := os.Stat(db.Path()); err != nil {\n    return fmt.Errorf(\"db missing, sync will fail: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"if err := db.SyncAndWait(ctx); err != nil {\n    var wrapped interface{ Unwrap() error }\n    _ = wrapped\n    log.Error(\"local sync stage failed\", \"err\", err)\n    // inspect errors.Is(err, sqliteErr) etc.\n}","preventionTips":["Ensure Open() completed and the WAL is healthy before forcing a sync.","Monitor free disk space where LTX files are written.","Avoid competing SQLite writers holding long checkpoints.","Test crash recovery scenarios; corrupted WAL needs reset/restore."],"tags":["database","wal","error-wrapping"],"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"}