{"record":{"id":"93660ff2b737a00d","repo":"benbjohnson/litestream","slug":"create-buffer-directory-w","errorCode":null,"errorMessage":"create buffer directory: %w","messagePattern":"create buffer directory: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"vfs.go","lineNumber":2193,"sourceCode":"\treturn pr\n}\n\n// initWriteBuffer initializes the write buffer file for durability.\n// Any existing buffer content is discarded since unsync'd changes are lost on restart.\n// This function acquires f.mu internally.\nfunc (f *VFSFile) initWriteBuffer() error {\n\tf.mu.Lock()\n\tdefer f.mu.Unlock()\n\treturn f.initWriteBufferWithLock()\n}\n\n// initWriteBufferWithLock initializes the write buffer file for durability.\n// Any existing buffer content is discarded since unsync'd changes are lost on restart.\n// Caller must hold f.mu.\nfunc (f *VFSFile) initWriteBufferWithLock() error {\n\t// Ensure parent directory exists\n\tif err := os.MkdirAll(filepath.Dir(f.bufferPath), 0755); err != nil {\n\t\treturn fmt.Errorf(\"create buffer directory: %w\", err)\n\t}\n\n\t// Open or create buffer file, truncating any existing content\n\tfile, err := os.OpenFile(f.bufferPath, os.O_RDWR|os.O_CREATE|os.O_TRUNC, 0644)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"open buffer file: %w\", err)\n\t}\n\tf.bufferFile = file\n\tf.bufferNextOff = 0\n\n\treturn nil\n}\n\n// writeToBuffer writes a dirty page to the write buffer for durability.\n// If the page already exists in the buffer, it overwrites at the same offset.\n// Otherwise, it appends to the end of the file.\n// Must be called with f.mu held.\nfunc (f *VFSFile) writeToBuffer(pgno uint32, data []byte) error {","sourceCodeStart":2175,"sourceCodeEnd":2211,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/vfs.go#L2175-L2211","documentation":"initWriteBufferWithLock creates the parent directory of the VFS write-buffer file with os.MkdirAll before opening the buffer. This error wraps that MkdirAll failure, meaning the buffer directory could not be created — usually a permissions problem on an ancestor path, or an ancestor existing as a non-directory file.","triggerScenarios":"Opening a VFS file with write buffering enabled when filepath.Dir(f.bufferPath) cannot be created: parent dir not writable, path component is a regular file, read-only filesystem, or sandboxed process lacking write access.","commonSituations":"Misconfigured buffer path pointing inside a file path or read-only mount; running the service as an unprivileged user with an ownership mismatch; containers with read-only root filesystems; SELinux/AppArmor denials.","solutions":["Check ownership/permissions of each path component leading to the buffer dir; create the parent manually with correct ownership if needed.","Fix the bufferPath configuration so it points to a writable directory, not inside a file or read-only mount.","In containers, mount a writable volume for the buffer directory or set a writable working path.","Inspect the wrapped syscall error: EACCES → permissions, ENOTDIR → a path component is a file, EROFS → read-only filesystem."],"exampleFix":"// before\nbufferPath: /var/tmp/litestream/buffers/app.db.buffer  // /var/tmp/litestream owned by root\n// after\nsudo mkdir -p /var/tmp/litestream/buffers && sudo chown app:app /var/tmp/litestream/buffers","handlingStrategy":"validation","validationCode":"dir := filepath.Dir(bufferPath)\nif fi, err := os.Stat(dir); err != nil {\n    if err := os.MkdirAll(dir, 0o755); err != nil { return fmt.Errorf(\"buffer dir not creatable: %w\", err) }\n} else if !fi.IsDir() { return fmt.Errorf(\"%s is not a directory\", dir) }","typeGuard":null,"tryCatchPattern":"if err := db.Open(ctx); err != nil {\n    if strings.Contains(err.Error(), \"create buffer directory\") {\n        return fmt.Errorf(\"fix bufferPath permissions/config: %w\", err)\n    }\n    return err\n}","preventionTips":["Pre-create the buffer directory in deployment with correct ownership","Verify bufferPath points to a writable dir, not a file path","Mount a writable volume in containers for buffer state"],"tags":["go","filesystem","permissions","write-buffer"],"backgroundTag":"mkdir-permission-denied","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"}