{"record":{"id":"7dcbfd2d2a4f1264","repo":"benbjohnson/litestream","slug":"remove-l0-directory-w","errorCode":null,"errorMessage":"remove L0 directory: %w","messagePattern":"remove L0 directory: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"db.go","lineNumber":1616,"sourceCode":"\tif err != nil {\n\t\treturn fmt.Errorf(\"get replica position: %w\", err)\n\t} else if replicaInfo.MaxTXID == 0 {\n\t\treturn nil // No remote replica data yet\n\t}\n\n\t// Check if database is behind replica\n\tif dbPos.TXID >= replicaInfo.MaxTXID {\n\t\treturn nil // Database is ahead or equal\n\t}\n\n\tdb.Logger.Info(\"detected database behind replica\",\n\t\t\"db_txid\", dbPos.TXID,\n\t\t\"replica_txid\", replicaInfo.MaxTXID)\n\n\t// Clear local L0 files\n\tl0Dir := db.LTXLevelDir(0)\n\tif err := os.RemoveAll(l0Dir); err != nil && !os.IsNotExist(err) {\n\t\treturn fmt.Errorf(\"remove L0 directory: %w\", err)\n\t}\n\tdb.invalidatePosCache()\n\tif err := internal.MkdirAll(l0Dir, db.dirInfo); err != nil {\n\t\treturn fmt.Errorf(\"recreate L0 directory: %w\", err)\n\t}\n\n\t// Fetch latest L0 LTX file from replica\n\tminTXID, maxTXID := replicaInfo.MinTXID, replicaInfo.MaxTXID\n\treader, err := db.Replica.Client.OpenLTXFile(ctx, 0, minTXID, maxTXID, 0, 0)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"open remote L0 file: %w\", err)\n\t}\n\tdefer func() { _ = reader.Close() }()\n\n\t// Write to temp file and atomically rename\n\tlocalPath := db.LTXPath(0, minTXID, maxTXID)\n\ttmpPath := localPath + \".tmp\"\n","sourceCodeStart":1598,"sourceCodeEnd":1634,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/db.go#L1598-L1634","documentation":"When the database is behind the replica, Litestream clears the local L0 files by removing the level-0 LTX directory before re-fetching from the replica. This error wraps a failure of os.RemoveAll on that directory. It almost always indicates a filesystem-level problem (permissions, I/O error), since a missing directory is explicitly tolerated.","triggerScenarios":"checkDatabaseBehindReplica detects dbPos.TXID < replicaInfo.MaxTXID, calls os.RemoveAll(db.LTXLevelDir(0)), and the OS returns an error other than NotExist (e.g. EACCES, EBUSY, EIO).","commonSituations":"Litestream runs as a user without write permission on the LTX directory; the directory is mounted read-only; a file inside is held/immutable (or on Windows locked by another process); NFS/overlay filesystem I/O errors.","solutions":["Check ownership/permissions of the L0 directory and that the litestream process user can write to it (ls -ld).","Verify the volume is not mounted read-only (mount | grep, or container volume config).","Look for processes holding files in the directory (lsof) and stop them (e.g. another litestream instance).","Inspect the wrapped OS error (%w) for the exact errno; fix the underlying filesystem condition and let the next sync retry."],"exampleFix":"// before: running litestream as wrong user\n$ litestream replicate -config /etc/litestream.yml\n// after: ensure data dir is writable by the service user\n$ chown -R litestream:litestream /var/lib/db && systemctl restart litestream","handlingStrategy":"validation","validationCode":"// Ensure L0 dir is writable by the process user\ninfo, err := os.Stat(l0Dir)\nif err == nil && info.IsDir() {\n    if err := os.WriteFile(l0Dir+\"/.probe\", []byte(\"x\"), 0o600); err != nil {\n        log.Fatalf(\"L0 dir not writable: %v\", err)\n    }\n    os.Remove(l0Dir + \"/.probe\")\n}","typeGuard":"null","tryCatchPattern":"if err := os.RemoveAll(dir); err != nil && !os.IsNotExist(err) {\n    return fmt.Errorf(\"remove L0 directory: %w\", err)\n} // inspect wrapped errno: EACCES -> chown, EROFS -> remount rw, EBUSY -> stop competing process","preventionTips":["Run litestream under a dedicated user owning the data dir","Never mount the data volume read-only for the writer","Ensure only one litestream instance manages a database","Check container volume mount modes (rw, not ro)"],"tags":["litestream","filesystem","permissions","l0"],"backgroundTag":"file-write-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"}