benbjohnson/litestream · error

encode page %d: %w

Error message

encode page %d: %w

What it means

After a dirty page is read from the write buffer, it is encoded into the LTX file via enc.EncodePage. This error wraps an EncodePage failure for the given page number — the page data could not be serialized or written to the LTX stream, invalidating the in-progress transaction file.

Source

Thrown at vfs.go:2163

		}

		// Encode each dirty page
		lockPgno := ltx.LockPgno(pageSize)
		for _, pgno := range pgnos {
			if pgno == lockPgno {
				continue // Skip lock page
			}

			// Read page data from buffer file
			bufferOff := dirtyOffsets[pgno]
			data := make([]byte, pageSize)
			if _, err = bufferFile.ReadAt(data, bufferOff); err != nil {
				err = fmt.Errorf("read page %d from buffer: %w", pgno, err)
				return
			}

			if err = enc.EncodePage(ltx.PageHeader{Pgno: pgno}, data); err != nil {
				err = fmt.Errorf("encode page %d: %w", pgno, err)
				return
			}
		}

		// Close encoder (writes trailer and page index)
		if err = enc.Close(); err != nil {
			err = fmt.Errorf("close encoder: %w", err)
			return
		}
	}()

	return pr
}

// initWriteBuffer initializes the write buffer file for durability.
// Any existing buffer content is discarded since unsync'd changes are lost on restart.
// This function acquires f.mu internally.
func (f *VFSFile) initWriteBuffer() error {

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Inspect the wrapped error: broken pipe → resolve replica connectivity and retry sync; ENOSPC → free staging disk space.
2. Ensure sync contexts are not cancelled mid-transaction (adequate shutdown grace period).
3. Check the write-buffer volume for hardware/filesystem errors if page data reads are also failing.
4. Retry the transaction — the partial LTX file is discarded and rebuilt on next sync.

if err := db.Sync(ctx); err != nil {
    var pageErr string
    if m := pageRe.FindStringSubmatch(err.Error()); m != nil { pageErr = m[1] } // "encode page N"
    if pageErr != "" { /* check upload pipe/disk, then retry sync */ }
    return err
}

When it happens

Trigger: enc.EncodePage(ltx.PageHeader{Pgno: pgno}, data) fails during sync: broken downstream writer (upload failed/cancelled), compression error on a corrupt page image, or disk error writing the staged LTX file.

Common situations: Replica upload pipe broken by network failure or context cancellation mid-transaction; ENOSPC on the staging disk; corrupted page data from a failing write buffer volume.

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

• encode header: %w
• close encoder: %w
• encode ltx snapshot header: %w
• write snapshot ltx: %w
• close ltx snapshot encoder: %w

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