{"record":{"id":"1744ffe211d9ba48","repo":"benbjohnson/litestream","slug":"encode-ltx-header-w","errorCode":null,"errorMessage":"encode ltx header: %w","messagePattern":"encode ltx header: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"db.go","lineNumber":2162,"sourceCode":"\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}\n\t\t\treturn result, fmt.Errorf(\"write ltx from db: %w\", err)\n\t\t}","sourceCodeStart":2144,"sourceCodeEnd":2180,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/db.go#L2144-L2180","documentation":"The LTX header encoding failed during sync staging for a non-disk-full reason. After opening the temp LTX file and creating the encoder, enc.EncodeHeader writes version, page size, commit, and WAL salt/offset metadata; any write/encode failure other than ENOSPC is wrapped here. The transaction was not replicated.","triggerScenarios":"Encoder I/O error on the temp file (bad sector, I/O error from the block device), or a file state change (fd invalidated) between open and header write.","commonSituations":"Failing disk / underlying storage reporting I/O errors (check dmesg); NFS/network filesystem glitches on the staging dir; container storage driver errors.","solutions":["Check kernel logs (dmesg/journalctl) for I/O errors on the backing device and run fsck/replace hardware if errors appear.","If the staging dir is on NFS/network storage, move it to local disk.","Run `litestream reset` for the database to clear local LTX state and restart replication.","Retry replication after the transient I/O condition clears."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Precheck storage health on the staging volume:\n// dmesg | grep -i 'I/O error'  &&  smartctl -H /dev/<device>","typeGuard":null,"tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"encode ltx header\") && !errors.Is(err, ErrDiskFull) {\n    log.Printf(\"LTX header write failed (non-ENOSPC): %v — suspect storage/I-O error\", err)\n    // retry after health check; litestream reset if repeated\n}","preventionTips":["Run litestream state on healthy local disks, not NFS","Monitor dmesg/SMART for I/O errors","Avoid concurrent external access to litestream staging files"],"tags":["ltx","io-error","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"}