{"record":{"id":"9d2ea1964372284a","repo":"benbjohnson/litestream","slug":"disk-full","errorCode":null,"errorMessage":"disk full","messagePattern":"disk full","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"litestream.go","lineNumber":37,"sourceCode":"const (\n\tMetaDirSuffix = \"-litestream\"\n)\n\n// SQLite checkpoint modes.\nconst (\n\tCheckpointModePassive  = \"PASSIVE\"\n\tCheckpointModeFull     = \"FULL\"\n\tCheckpointModeRestart  = \"RESTART\"\n\tCheckpointModeTruncate = \"TRUNCATE\"\n)\n\n// Litestream errors.\nvar (\n\tErrNoSnapshots      = errors.New(\"no snapshots available\")\n\tErrChecksumMismatch = errors.New(\"invalid replica, checksum mismatch\")\n\tErrLTXCorrupted     = errors.New(\"ltx file corrupted\")\n\tErrLTXMissing       = errors.New(\"ltx file missing\")\n\tErrDiskFull         = errors.New(\"disk full\")\n)\n\n// LTXError provides detailed context for LTX file errors with recovery hints.\ntype LTXError struct {\n\tOp      string // Operation that failed (e.g., \"open\", \"read\", \"validate\")\n\tPath    string // File path\n\tLevel   int    // LTX level (0 = L0, etc.)\n\tMinTXID uint64 // Minimum transaction ID\n\tMaxTXID uint64 // Maximum transaction ID\n\tErr     error  // Underlying error\n\tHint    string // Recovery hint for users\n}\n\nfunc (e *LTXError) Error() string {\n\tif e.Path != \"\" {\n\t\treturn e.Op + \" ltx file \" + e.Path + \": \" + e.Err.Error()\n\t}\n\treturn e.Op + \" ltx file: \" + e.Err.Error()","sourceCodeStart":19,"sourceCodeEnd":55,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/litestream.go#L19-L55","documentation":"ErrDiskFull is litestream's sentinel error indicating the local disk ran out of space while replicating. It is wrapped into an LTXError with operation context (e.g. 'stage-mkdir') and is also matched against syscall.ENOSPC so OS-level 'no space left on device' errors are recognized. Because litestream stages WAL changes as LTX files on disk before upload, any filesystem write that exhausts space surfaces here.","triggerScenarios":"MkdirAll of the staging directory during LTX write (db.go:2115) fails with ENOSPC; other internal writes checked by isDiskFullError (db.go:1528) return ENOSPC or ErrDiskFull; the disk holding the litestream working/staging directory is full while syncing a transaction.","commonSituations":"Small disk or full partition on the host running litestream; tmpfs mount for the staging dir running out of space; a runaway database generating more WAL than disk can hold; quota-limited container filesystems.","solutions":["Free disk space on the filesystem containing the litestream staging directory (df -h, remove old logs/tmp files)","Move the litestream working directory or staging path to a volume with sufficient headroom for peak WAL volume","Add disk-space monitoring/alerting and automated cleanup of the staging area so ENOSPC never occurs mid-sync","If the error came from a wrapped LTXError, check its Op/Path fields to find exactly which write failed and enlarge that location"],"exampleFix":"// before (ignoring disk state until failure)\nif err := db.Sync(ctx); err != nil {\n    log.Fatal(err)\n}\n// after\nif err := db.Sync(ctx); err != nil {\n    if errors.Is(err, litestream.ErrDiskFull) || errors.Is(err, syscall.ENOSPC) {\n        freeSpaceOrHalt(db.Path()) // e.g. cleanup + alert before retrying\n    }\n    log.Fatal(err)\n}","handlingStrategy":"try-catch","validationCode":"func hasDiskHeadroom(path string, need uint64) error {\n    var st syscall.Statfs_t\n    if err := syscall.Statfs(path, &st); err != nil {\n        return err\n    }\n    avail := uint64(st.Bavail) * uint64(st.Bsize)\n    if avail < need {\n        return fmt.Errorf(\"only %d bytes free at %s\", avail, path)\n    }\n    return nil\n}","typeGuard":"func isDiskFull(err error) bool {\n    return errors.Is(err, litestream.ErrDiskFull) || errors.Is(err, syscall.ENOSPC)\n}","tryCatchPattern":"if err := db.Sync(ctx); err != nil {\n    if isDiskFull(err) {\n        alertAndFreeSpace(err) // page operator, clean staging dir, then retry\n    } else {\n        return err\n    }\n}","preventionTips":["Monitor free space on the litestream staging filesystem and alert well before 100%","Size the disk for peak WAL throughput, not average","Keep retention/cleanup jobs running so old staged files do not accumulate","Run litestream on a dedicated volume to contain disk growth"],"tags":["disk-space","filesystem","replication","enospc"],"backgroundTag":"disk-full","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"}