{"record":{"id":"bddd26f0572b060f","repo":"benbjohnson/litestream","slug":"create-temp-dir-for-write-buffer-w","errorCode":null,"errorMessage":"create temp dir for write buffer: %w","messagePattern":"create temp dir for write buffer: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"vfs.go","lineNumber":236,"sourceCode":"\tif writeEnabled {\n\t\tf.writeEnabled = true\n\t\tf.dirty = make(map[uint32]int64)\n\t\tf.syncInterval = syncInterval\n\t\tif f.syncInterval == 0 {\n\t\t\tf.syncInterval = DefaultSyncInterval\n\t\t}\n\n\t\twriteSeq := atomic.AddUint64(&vfs.writeSeq, 1)\n\t\tif bufferPath != \"\" {\n\t\t\tif writeSeq == 1 {\n\t\t\t\tf.bufferPath = bufferPath\n\t\t\t} else {\n\t\t\t\tf.bufferPath = bufferPath + \".\" + strconv.FormatUint(writeSeq, 10)\n\t\t\t}\n\t\t} else {\n\t\t\tdir, err := vfs.ensureTempDir()\n\t\t\tif err != nil {\n\t\t\t\treturn nil, 0, fmt.Errorf(\"create temp dir for write buffer: %w\", err)\n\t\t\t}\n\t\t\tf.bufferPath = filepath.Join(dir, \"write-buffer-\"+strconv.FormatUint(writeSeq, 10))\n\t\t}\n\n\t\t// Initialize compaction if enabled\n\t\tif vfs.CompactionEnabled {\n\t\t\tf.compactor = NewCompactor(client, f.logger)\n\t\t}\n\t}\n\n\t// Initialize hydration support if enabled\n\tif hydrationEnabled {\n\t\tif hydrationPath != \"\" {\n\t\t\tf.hydrationPath = hydrationPath\n\t\t\tf.hydrationPersistent = true\n\t\t} else {\n\t\t\tdir, err := vfs.ensureTempDir()\n\t\t\tif err != nil {","sourceCodeStart":218,"sourceCodeEnd":254,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/vfs.go#L218-L254","documentation":"In openMainDB, when no explicit bufferPath is configured, Litestream calls vfs.ensureTempDir() to obtain (or create) a temporary directory used to buffer writes before they are staged for upload. This error wraps any failure of that directory creation. Litestream throws it because the write buffer requires local disk space and a writable directory to operate.","triggerScenarios":"Opening a VFS database when the temp directory cannot be created or found: os.TempDir() points to a non-writable path, TMPDIR is set to a nonexistent or permission-denied directory, or the filesystem holding /tmp is full/read-only.","commonSituations":"Containers with read-only root filesystems and no tmpfs mounted at /tmp; serverless environments with restricted /tmp; running as a non-root user with TMPDIR pointing at another user's directory; disk-full conditions on small instances.","solutions":["Point TMPDIR (or os.TempDir's source) at a writable directory before opening the connection.","Configure an explicit buffer path in the VFS config so Litestream skips the temp-dir lookup and uses your own writable location.","Mount a writable tmpfs/emptyDir volume at /tmp in containers and ensure the process user owns it.","Check disk space and permissions (ls -ld $TMPDIR; df -h) on the target filesystem."],"exampleFix":"// before\n// TMPDIR=/nonexistent, container fs read-only\ndb, err := sql.Open(\"sqlite\", \"file:app.db?vfs=litestream&replica_url=s3://bucket/app.db\")\n\n// after\nos.Setenv(\"TMPDIR\", \"/var/tmp/app\") // writable volume\ndb, err := sql.Open(\"sqlite\", \"file:app.db?vfs=litestream&replica_url=s3://bucket/app.db\")","handlingStrategy":"validation","validationCode":"tmp := os.TempDir()\nif fi, err := os.Stat(tmp); err != nil || !fi.IsDir() {\n    return fmt.Errorf(\"temp dir %q unusable: %w\", tmp, err)\n}\nprobe, err := os.CreateTemp(tmp, \"litestream-probe-*\")\nif err != nil { return err }\nprobe.Remove()","typeGuard":null,"tryCatchPattern":"db, err := sql.Open(\"sqlite\", dsn)\nif err != nil && strings.Contains(err.Error(), \"create temp dir for write buffer\") {\n    os.Setenv(\"TMPDIR\", \"/var/tmp/app\")\n    return reopenDB(dsn)\n}","preventionTips":["Ensure TMPDIR points to an existing, writable directory in every deployment","Mount a writable tmpfs/emptyDir at /tmp in containers with read-only root filesystems","Configure an explicit buffer path in VFSConfig to bypass temp-dir resolution","Monitor free disk space on the temp filesystem; writes fail when it is full"],"tags":["filesystem","temp-dir","vfs","permissions"],"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-14T05:17:10.506Z"}