benbjohnson/litestream · error

fetch page %d: %w

Error message

fetch page %d: %w

What it means

While building the snapshot, Snapshot reads each required page from remote LTX storage via FetchPage; this wraps any storage/decoding failure with the failing page number. It means one page's data could not be fetched from the replica storage, so the snapshot stream is aborted.

Source

Thrown at vfs.go:3063

		if err := enc.EncodeHeader(ltx.Header{
			Version:   ltx.Version,
			Flags:     ltx.HeaderFlagNoChecksum,
			PageSize:  pageSize,
			Commit:    commit,
			MinTXID:   1,
			MaxTXID:   pos.TXID,
			Timestamp: time.Now().UnixMilli(),
		}); err != nil {
			pw.CloseWithError(fmt.Errorf("encode header: %w", err))
			return
		}

		for _, pgno := range pgnos {
			elem := pages[pgno]
			_, data, err := FetchPage(ctx, f.client, elem.Level, elem.MinTXID, elem.MaxTXID, elem.Offset, elem.Size)
			if err != nil {
				pw.CloseWithError(fmt.Errorf("fetch page %d: %w", pgno, err))
				return
			}
			if err := enc.EncodePage(ltx.PageHeader{Pgno: pgno}, data); err != nil {
				pw.CloseWithError(fmt.Errorf("encode page %d: %w", pgno, err))
				return
			}
		}

		if err := enc.Close(); err != nil {
			pw.CloseWithError(fmt.Errorf("close encoder: %w", err))
			return
		}
		pw.Close()
	}()

	return f.client.WriteLTXFile(ctx, SnapshotLevel, 1, pos.TXID, pr)
}

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Re-sync the database so local LTX state matches what remote storage holds
2. Check remote storage for the LTX file covering the page's TXID range; restore missing objects from backup if pruned
3. Run litestream reset (or the documented reset path) to clear corrupted local LTX state and re-replicate
4. Retry after confirming network/connectivity to the replica storage

info, err := file.Snapshot(ctx)
if err != nil && strings.Contains(err.Error(), "fetch page") {
    // check remote LTX availability, then retry with backoff
    time.Sleep(backoff)
    info, err = file.Snapshot(ctx)
}

When it happens

Trigger: FetchPage(ctx, f.client, elem.Level, elem.MinTXID, elem.MaxTXID, elem.Offset, elem.Size) returns an error during Snapshot — missing LTX file for the needed TXID range, network failure, or corrupted remote object.

Common situations: Remote replicas pruned/compacted away the LTX files covering the needed TXIDs; S3/network outage mid-snapshot; restored storage missing objects; stale local pos pointing at TXIDs no longer in remote.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• close iterator: %w
• fetch ltx files: %w
• list generations: %w
• list snapshots for generation %s: %w
• download snapshot: %w

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