{"record":{"id":"1df0cabf7a3b6981","repo":"benbjohnson/litestream","slug":"stage-write","errorCode":"stage-write","errorMessage":"%w: %w (ErrDiskFull)","messagePattern":"%w: %w \\(ErrDiskFull\\)","errorType":"error_code","errorClass":"LTXError","httpStatus":null,"severity":"critical","filePath":"db.go","lineNumber":2160,"sourceCode":"\tenc, err := ltx.NewEncoder(ltxFile)\n\tif err != nil {\n\t\treturn result, fmt.Errorf(\"new ltx encoder: %w\", err)\n\t}\n\tif err := enc.EncodeHeader(ltx.Header{\n\t\tVersion:   ltx.Version,\n\t\tFlags:     ltx.HeaderFlagNoChecksum,\n\t\tPageSize:  uint32(db.pageSize),\n\t\tCommit:    commit,\n\t\tMinTXID:   txID,\n\t\tMaxTXID:   txID,\n\t\tTimestamp: timestamp.UnixMilli(),\n\t\tWALOffset: info.offset,\n\t\tWALSize:   sz,\n\t\tWALSalt1:  rd.salt1,\n\t\tWALSalt2:  rd.salt2,\n\t}); err != nil {\n\t\tif isDiskFullError(err) {\n\t\t\treturn result, NewLTXError(\"stage-write\", tmpFilename, 0, uint64(txID), uint64(txID), fmt.Errorf(\"%w: %w\", ErrDiskFull, err))\n\t\t}\n\t\treturn result, fmt.Errorf(\"encode ltx header: %w\", err)\n\t}\n\n\t// If we need a full snapshot, then copy from the database & WAL.\n\t// Otherwise, just copy incrementally from the WAL.\n\tif info.snapshotting {\n\t\tdb.setSyncDiagPhase(diagPhaseWriteLTXFromDB,\n\t\t\tfunc(s *diagState) {\n\t\t\t\ts.txID = txID\n\t\t\t\ts.walSize = sz\n\t\t\t\ts.snapshotting = true\n\t\t\t\ts.reason = info.reason\n\t\t\t})\n\t\tif err := db.writeLTXFromDB(ctx, enc, walFile, commit, pageMap); err != nil {\n\t\t\tif isDiskFullError(err) {\n\t\t\t\treturn result, NewLTXError(\"stage-write\", tmpFilename, 0, uint64(txID), uint64(txID), fmt.Errorf(\"%w: %w\", ErrDiskFull, err))\n\t\t\t}","sourceCodeStart":2142,"sourceCodeEnd":2178,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/db.go#L2142-L2178","documentation":"While writing the LTX header during sync staging, the encoder write failed with a disk-full condition. Litestream detects ENOSPC-class errors via isDiskFullError and re-reports them as a structured LTXError with code \"stage-write\" wrapping ErrDiskFull. The local disk (not cloud storage) ran out of space while creating the LTX file.","triggerScenarios":"Replicating a large transaction (snapshot or big WAL frame set) when the volume holding the litestream data directory has insufficient free space for even the LTX header write.","commonSituations":"Small container/disk quota for /var/lib/litestream; snapshot of a multi-GB database on a nearly full disk; log files or core dumps consuming the same volume; Docker overlay limit reached.","solutions":["Free space on the volume holding the litestream data directory (df -h, delete stale files/logs).","Move the litestream data/replica directory to a larger volume and update the config path.","Raise the container/disk quota if running in Docker/Kubernetes.","Enable the `auto-recover` replica option or run `litestream reset` for the DB after freeing space, since a failed staged LTX can leave local state requiring reset.","Add monitoring/alerting on disk usage (e.g. df threshold) so replication never races ENOSPC."],"exampleFix":"// before\ncf.yml: litestream data on 5GB volume, db is 8GB -> ENOSPC at stage-write\n// after\n# move data dir to larger volume and update config\npath: /data/litestream/db   # /data is a 100GB volume","handlingStrategy":"validation","validationCode":"func assertDiskHeadroom(path string, needBytes uint64) error {\n    var st syscall.Statfs_t\n    if err := syscall.Statfs(path, &st); err != nil { return err }\n    free := uint64(st.Bavail) * uint64(st.Bsize)\n    if free < needBytes {\n        return fmt.Errorf(\"only %d bytes free at %s, need %d\", free, path, needBytes)\n    }\n    return null_or_nil()\n}","typeGuard":null,"tryCatchPattern":"if errors.Is(err, ErrDiskFull) {\n    alertDiskFull(filepath.Dir(stagingPath))\n    // free space / expand volume, then restart litestream or litestream reset\n}","preventionTips":["Size the staging volume >= DB size + WAL headroom before first replication","Alert on disk usage at 80%","Isolate litestream state on its own volume so other processes can't fill it","Set container ephemeral-storage requests/limits appropriately"],"tags":["disk-full","enospc","ltx","replication"],"backgroundTag":"file-write-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"}