{"record":{"id":"4897956c64a7c7f1","repo":"benbjohnson/litestream","slug":"sync-database-w","errorCode":null,"errorMessage":"sync database: %w","messagePattern":"sync database: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"store.go","lineNumber":450,"sourceCode":"// the database sync executor and the replica sync lock.\nfunc (s *Store) SyncDB(ctx context.Context, path string, wait bool) (SyncDBResult, error) {\n\tdb := s.FindDB(path)\n\tif db == nil {\n\t\treturn SyncDBResult{}, fmt.Errorf(\"%w: %s\", ErrDatabaseNotFound, path)\n\t}\n\n\tif !db.IsOpen() {\n\t\treturn SyncDBResult{}, fmt.Errorf(\"%w: %s\", ErrDatabaseNotOpen, path)\n\t}\n\n\t_, beforeTXID, err := db.MaxLTX()\n\tif err != nil {\n\t\treturn SyncDBResult{}, fmt.Errorf(\"read position before sync: %w\", err)\n\t}\n\n\tif wait {\n\t\tif err := db.SyncAndWait(ctx); err != nil {\n\t\t\treturn SyncDBResult{}, fmt.Errorf(\"sync database: %w\", err)\n\t\t}\n\t} else {\n\t\tif err := db.Sync(ctx); err != nil {\n\t\t\treturn SyncDBResult{}, fmt.Errorf(\"sync database: %w\", err)\n\t\t}\n\t}\n\n\t_, afterTXID, err := db.MaxLTX()\n\tif err != nil {\n\t\treturn SyncDBResult{}, fmt.Errorf(\"read position after sync: %w\", err)\n\t}\n\n\tvar replicatedTXID uint64\n\tif db.Replica != nil {\n\t\treplicatedTXID = uint64(db.Replica.Pos().TXID)\n\t}\n\n\treturn SyncDBResult{","sourceCodeStart":432,"sourceCodeEnd":468,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/store.go#L432-L468","documentation":"The database sync itself failed inside Store.SyncDB when wait=true, i.e. db.SyncAndWait(ctx) returned an error. SyncAndWait runs db.Sync (WAL -> LTX) followed by db.Replica.Sync (upload to replica storage) and blocks until both finish, so this error indicates the WAL could not be synced or the replica could not be updated. The underlying cause is wrapped with %w.","triggerScenarios":"SyncDB(ctx, path, true) where db.Sync fails (WAL read/checkpoint issue) or db.Replica.Sync fails (upload error); also SyncDB with wait=false where db.Sync fails.","commonSituations":"Replica storage credentials expired or bucket unavailable, network outage during upload, no replica configured while using SyncAndWait (returns \"no replica configured\"), or a corrupted WAL preventing checkpointing.","solutions":["Check the wrapped error for replica upload failures and verify storage credentials/network connectivity to the replica backend.","If using wait=true with no replica, switch to wait=false or configure a replica; SyncAndWait errors with \"no replica configured\" when db.Replica is nil.","Retry the sync after transient network errors; LTX uploads are idempotent per TXID.","If db.Sync fails repeatedly, inspect the SQLite database/WAL health and run litestream reset if local LTX state is corrupted."],"exampleFix":"// before\nres, err := store.SyncDB(ctx, path, true)\nif err != nil { return err }\n// after\nres, err := store.SyncDB(ctx, path, true)\nif err != nil {\n    if errors.Is(err, litestream.ErrNoReplica) || strings.Contains(err.Error(), \"no replica configured\") {\n        return store.SyncDB(ctx, path, false) // local sync only\n    }\n    return err\n}","handlingStrategy":"retry","validationCode":"// verify replica is configured before wait=true\nif wait && replicaConfig == nil {\n    wait = false // or configure a replica\n}","typeGuard":"func hasReplica(db *litestream.DB) bool {\n    return db != nil && db.Replica != nil\n}","tryCatchPattern":"err := doSync()\nif err != nil {\n    if isTransient(err) { // network/timeout errors\n        time.Sleep(backoff)\n        err = doSync()\n    }\n    if err != nil && strings.Contains(err.Error(), \"no replica configured\") {\n        return store.SyncDB(ctx, path, false)\n    }\n    return err\n}","preventionTips":["Ensure a replica is configured when using wait=true","Monitor storage credentials before expiry","Retry syncs with exponential backoff on network errors","Check DB and WAL health after abnormal shutdowns"],"tags":["go","litestream","sync","replication"],"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"}