benbjohnson/litestream · error

encode ltx header: %w

Error message

encode ltx header: %w

What it means

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.

Source

Thrown at db.go:2162

		return result, fmt.Errorf("new ltx encoder: %w", err)
	}
	if err := enc.EncodeHeader(ltx.Header{
		Version:   ltx.Version,
		Flags:     ltx.HeaderFlagNoChecksum,
		PageSize:  uint32(db.pageSize),
		Commit:    commit,
		MinTXID:   txID,
		MaxTXID:   txID,
		Timestamp: timestamp.UnixMilli(),
		WALOffset: info.offset,
		WALSize:   sz,
		WALSalt1:  rd.salt1,
		WALSalt2:  rd.salt2,
	}); err != nil {
		if isDiskFullError(err) {
			return result, NewLTXError("stage-write", tmpFilename, 0, uint64(txID), uint64(txID), fmt.Errorf("%w: %w", ErrDiskFull, err))
		}
		return result, fmt.Errorf("encode ltx header: %w", err)
	}

	// If we need a full snapshot, then copy from the database & WAL.
	// Otherwise, just copy incrementally from the WAL.
	if info.snapshotting {
		db.setSyncDiagPhase(diagPhaseWriteLTXFromDB,
			func(s *diagState) {
				s.txID = txID
				s.walSize = sz
				s.snapshotting = true
				s.reason = info.reason
			})
		if err := db.writeLTXFromDB(ctx, enc, walFile, commit, pageMap); err != nil {
			if isDiskFullError(err) {
				return result, NewLTXError("stage-write", tmpFilename, 0, uint64(txID), uint64(txID), fmt.Errorf("%w: %w", ErrDiskFull, err))
			}
			return result, fmt.Errorf("write ltx from db: %w", err)
		}

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Check kernel logs (dmesg/journalctl) for I/O errors on the backing device and run fsck/replace hardware if errors appear.
2. If the staging dir is on NFS/network storage, move it to local disk.
3. Run `litestream reset` for the database to clear local LTX state and restart replication.
4. Retry replication after the transient I/O condition clears.

// Precheck storage health on the staging volume:
// dmesg | grep -i 'I/O error'  &&  smartctl -H /dev/<device>

if err != nil && strings.Contains(err.Error(), "encode ltx header") && !errors.Is(err, ErrDiskFull) {
    log.Printf("LTX header write failed (non-ENOSPC): %v — suspect storage/I-O error", err)
    // retry after health check; litestream reset if repeated
}

When it happens

Trigger: 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.

Common situations: Failing disk / underlying storage reporting I/O errors (check dmesg); NFS/network filesystem glitches on the staging dir; container storage driver errors.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

• write ltx from db: %w
• write ltx from wal: %w
• close ltx encoder: %w
• open temp ltx file: %w
• new ltx encoder: %w

AI-assisted analysis of benbjohnson/litestream@4ed7a308f6 (2026-09-06). Data as JSON: /api/errors/1744ffe211d9ba48. Report an issue: GitHub.