{"record":{"id":"28337818cdcb3c4e","repo":"benbjohnson/litestream","slug":"sync-ltx-file-w","errorCode":null,"errorMessage":"sync ltx file: %w","messagePattern":"sync ltx file: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"db.go","lineNumber":2218,"sourceCode":"\t\ts.walSize = sz\n\t})\n\tif err := enc.Close(); err != nil {\n\t\tif isDiskFullError(err) {\n\t\t\treturn result, NewLTXError(\"stage-write\", tmpFilename, 0, uint64(txID), uint64(txID), fmt.Errorf(\"%w: %w\", ErrDiskFull, err))\n\t\t}\n\t\treturn result, fmt.Errorf(\"close ltx encoder: %w\", err)\n\t}\n\n\t// Sync & close LTX file.\n\tdb.setSyncDiagPhase(diagPhaseFsyncLTX, func(s *diagState) {\n\t\ts.txID = txID\n\t\ts.walSize = sz\n\t})\n\tif err := ltxFile.Sync(); err != nil {\n\t\tif isDiskFullError(err) {\n\t\t\treturn result, NewLTXError(\"stage-sync\", tmpFilename, 0, uint64(txID), uint64(txID), fmt.Errorf(\"%w: %w\", ErrDiskFull, err))\n\t\t}\n\t\treturn result, fmt.Errorf(\"sync ltx file: %w\", err)\n\t}\n\tif err := ltxFile.Close(); err != nil {\n\t\tif isDiskFullError(err) {\n\t\t\treturn result, NewLTXError(\"stage-close\", tmpFilename, 0, uint64(txID), uint64(txID), fmt.Errorf(\"%w: %w\", ErrDiskFull, err))\n\t\t}\n\t\treturn result, fmt.Errorf(\"close ltx file: %w\", err)\n\t}\n\n\t// Atomically rename file to final path.\n\tdb.setSyncDiagPhase(diagPhaseRenameLTX, func(s *diagState) {\n\t\ts.txID = txID\n\t\ts.walSize = sz\n\t})\n\tif err := os.Rename(tmpFilename, filename); err != nil {\n\t\tdb.maxLTXFileInfos.Lock()\n\t\tdelete(db.maxLTXFileInfos.m, 0) // clear cache if in unknown state\n\t\tdb.maxLTXFileInfos.Unlock()\n\t\tdb.invalidatePosCache()","sourceCodeStart":2200,"sourceCodeEnd":2236,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/db.go#L2200-L2236","documentation":"The LTX file fsync failed with an error that was NOT classified as disk-full. Litestream wraps the raw OS error with 'sync ltx file:' so the failure is attributed to the durability flush of the in-progress LTX file. The temp file is left behind and the transaction is not committed to LTX.","triggerScenarios":"ltxFile.Sync() at db.go:2214 returned an I/O error other than ENOSPC: EIO from failing hardware, EINVAL from unusual mount options, EROFS, or a network filesystem (NFS/EFS) reporting a flush error.","commonSituations":"Disk or controller hardware errors; mounting the data dir on NFS/S3-FS where fsync is unreliable; read-only remount after a filesystem error; container storage driver failures.","solutions":["Inspect the wrapped OS error (dmesg / journalctl) to identify the underlying I/O problem.","Run filesystem checks (fsck) and monitor SMART health of the underlying device.","Move the database directory to a local, reliable filesystem instead of a network mount.","Delete the stale temp file and retry the sync once the underlying issue is resolved."],"exampleFix":"// before\n// generic handling loses the failing file stage\nlog.Println(err)\n// after\nvar ltxErr *LTXError\nif errors.As(err, &ltxErr) {\n\tlog.Printf(\"ltx stage=%s file=%s: %v\", ltxErr.Stage, ltxErr.Filename, ltxErr)\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":"func isLTXStageErr(err error) (stage string, ok bool) {\n\tvar e *LTXError\n\tif errors.As(err, &e) { return e.Stage, true }\n\treturn \"\", false\n}","tryCatchPattern":"if err := db.Sync(ctx); err != nil {\n\tvar le *LTXError\n\tif errors.As(err, &le) && le.Stage == \"stage-sync\" {\n\t\t// inspect wrapped OS error; check dmesg for device issues\n\t}\n\treturn err\n}","preventionTips":["Keep the database on a local, POSIX-compliant filesystem, not NFS.","Monitor SMART/device health and filesystem errors.","Avoid read-only remount scenarios by supervising mount state.","Clean up orphaned temp LTX files after failures."],"tags":["fsync","filesystem","io-error","storage"],"backgroundTag":"file-write-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"}