{"record":{"id":"154b2810725d1583","repo":"benbjohnson/litestream","slug":"clear-write-buffer-w","errorCode":null,"errorMessage":"clear write buffer: %w","messagePattern":"clear write buffer: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"vfs.go","lineNumber":2056,"sourceCode":"\t\tf.cache.Add(pgno, cachedData)\n\t}\n\n\t// Apply synced pages to hydrated file if hydration is complete\n\t// Must be done before clearing f.dirty since we need the page offsets\n\tif f.hydrator != nil && f.hydrator.Complete() {\n\t\tif err := f.applySyncedPagesToHydratedFile(); err != nil {\n\t\t\tf.logger.Error(\"failed to apply synced pages to hydrated file\", \"error\", err)\n\t\t\t// Don't fail the sync - hydration will catch up on next poll\n\t\t}\n\t}\n\n\t// Clear dirty pages\n\tf.dirty = make(map[uint32]int64)\n\n\t// Clear write buffer after successful sync\n\tif err := f.clearWriteBuffer(); err != nil {\n\t\tf.logger.Error(\"failed to clear write buffer\", \"error\", err)\n\t\treturn fmt.Errorf(\"clear write buffer: %w\", err)\n\t}\n\n\treturn nil\n}\n\n// checkForConflict checks if the remote has newer transactions than expected.\n// Must be called with f.mu held.\nfunc (f *VFSFile) checkForConflict(ctx context.Context) error {\n\t// Get latest remote position\n\titr, err := f.client.LTXFiles(ctx, 0, f.expectedTXID, false)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"check remote position: %w\", err)\n\t}\n\tdefer itr.Close()\n\n\tvar remoteTXID ltx.TXID\n\tfor itr.Next() {\n\t\tinfo := itr.Item()","sourceCodeStart":2038,"sourceCodeEnd":2074,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/vfs.go#L2038-L2074","documentation":"This error is returned after a successful sync when VFSFile.clearWriteBuffer() fails. Litestream's VFS layer stages dirty page data in a temporary write-buffer file for durability; after an LTX transaction commits, the buffer must be cleared (truncated/reset) so it can accumulate the next transaction's pages. The wrap preserves the underlying OS or I/O error from that cleanup step.","triggerScenarios":"VFSFile sync succeeds remotely but the subsequent clearWriteBuffer() call fails to truncate or reset the buffer file (disk I/O error, file deleted or locked underneath the VFS, disk full, stale file descriptor after restart).","commonSituations":"Disk-full conditions on the node hosting the buffer file; the buffer file removed by tmp cleaners or another process; running inside containers with read-only or small tmp volumes; crash-recovery leaving the buffer file in a bad state.","solutions":["Check disk space and filesystem health on the volume holding the buffer file (inspect the underlying error wrapped by this message for ENOSPC/EIO).","Verify nothing else deletes or locks the buffer file while the database is open; exclude it from tmp-cleanup jobs.","Restart the process: initWriteBufferWithLock truncates and rebuilds the buffer on open, clearing stale state.","If the wrapped error is permission-related, fix ownership/mode of the buffer directory (0755) and file (0644)."],"exampleFix":"// before: buffer file cleaned up externally\n// /etc/tmpfiles.d/cleanup.conf\n// D /var/tmp/litestream 0755 root root -\n// after: persist buffer dir outside tmp cleaner scope\n// bufferPath: /var/lib/litestream/buffers/db.buffer","handlingStrategy":"try-catch","validationCode":"// Go: check volume writability before opening the DB\nif f, err := os.Stat(filepath.Dir(bufferPath)); err != nil || !f.IsDir() { return fmt.Errorf(\"buffer dir missing: %w\", err) }","typeGuard":null,"tryCatchPattern":"if err := db.Sync(ctx); err != nil {\n    if strings.Contains(err.Error(), \"clear write buffer\") {\n        logger.Error(\"buffer cleanup failed; restarting DB handle to rebuild buffer\", \"err\", err)\n        // reopen DB to re-init write buffer\n    }\n    return err\n}","preventionTips":["Keep buffer files on a persistent volume excluded from tmp-cleaners/logrotate","Alert on disk usage of the buffer volume before it fills","Never share or delete the buffer file externally while the DB is open"],"tags":["go","vfs","write-buffer","disk-io"],"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-14T00:17:10.932Z"}