{"record":{"id":"a0cdfd05ef1d0837","repo":"benbjohnson/litestream","slug":"initialize-write-buffer-w","errorCode":null,"errorMessage":"initialize write buffer: %w","messagePattern":"initialize write buffer: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"vfs.go","lineNumber":1153,"sourceCode":"\t}\n\tf.cache = cache\n\n\t// Determine the current position based off the latest LTX file.\n\tvar pos ltx.Pos\n\tif len(infos) > 0 {\n\t\tpos = ltx.Pos{TXID: infos[len(infos)-1].MaxTXID}\n\t}\n\tf.pos = pos\n\n\t// Initialize write support TXID tracking\n\tif f.writeEnabled {\n\t\tf.expectedTXID = pos.TXID\n\t\tf.pendingTXID = pos.TXID + 1\n\t\tf.logger.Debug(\"write support enabled\", \"expectedTXID\", f.expectedTXID, \"pendingTXID\", f.pendingTXID)\n\n\t\t// Initialize write buffer file for durability (discards any existing buffer)\n\t\tif err := f.initWriteBuffer(); err != nil {\n\t\t\treturn fmt.Errorf(\"initialize write buffer: %w\", err)\n\t\t}\n\t}\n\n\t// Build the page index so we can lookup individual pages.\n\tif err := f.buildIndex(f.ctx, infos); err != nil {\n\t\tf.logger.Error(\"cannot build index\", \"error\", err)\n\t\treturn fmt.Errorf(\"cannot build index: %w\", err)\n\t}\n\n\t// Start background hydration if enabled\n\tif f.hydrationPath != \"\" {\n\t\tif err := f.initHydration(infos); err != nil {\n\t\t\tf.logger.Warn(\"hydration initialization failed, continuing without hydration\", \"error\", err)\n\t\t\tf.hydrationPath = \"\"\n\t\t}\n\t}\n\n\t// Continuously monitor the replica client for new LTX files.","sourceCodeStart":1135,"sourceCodeEnd":1171,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/vfs.go#L1135-L1171","documentation":"Raised during VFSFile.Open when write support is enabled and initializing the durable write buffer file fails. The write buffer is a local file that accumulates pending pages for durability before they are replicated; if it cannot be created/opened, the database cannot be opened in writable mode.","triggerScenarios":"initWriteBuffer fails because the buffer directory does not exist or is not writable, the disk is full, an OS open/create error occurs, or the existing buffer file is locked/corrupt and cannot be discarded.","commonSituations":"Buffer path on a read-only or full filesystem; wrong buffer directory permissions; leftover buffer file held by another process; container with a read-only root filesystem.","solutions":["Check that the write buffer path exists, is writable, and has free space (df, ls -l)","Ensure no other litestream/VFS process holds the buffer file open","Fix filesystem mounts (make read-only mounts writable or relocate the buffer path)","Disable write mode if only reads are needed (don't enable writes on this file)"],"exampleFix":"// before\nvfs.NewVFS(..., CacheSize, WriteBufferDir: \"/ro-mount/buf\")\n// after\n// ensure dir is writable before enabling writes\nos.MkdirAll(bufDir, 0o755); checkWritable(bufDir)\nvfs.NewVFS(..., WriteBufferDir: bufDir)","handlingStrategy":"validation","validationCode":"if err := os.MkdirAll(bufDir, 0o755); err != nil { return err }\nif err := checkWritable(bufDir); err != nil { return err } // test-create+remove a temp file","typeGuard":"func dirWritable(dir string) bool { f, err := os.CreateTemp(dir, \"t\"); if err != nil { return false }; f.Close(); os.Remove(f.Name()); return true }","tryCatchPattern":"if err := file.Open(ctx); err != nil {\n    var we *fs.PathError\n    if errors.As(err, &we) && strings.Contains(err.Error(), \"initialize write buffer\") {\n        logger.Error(\"write buffer unusable; open in read-only mode instead\", \"error\", err)\n    }\n    return err\n}","preventionTips":["Pre-create and test-writability of the buffer directory","Keep buffer dir off read-only/full volumes","Ensure a single process owns the buffer file at a time"],"tags":["write-buffer","durability","filesystem","open"],"backgroundTag":"file-open-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"}