benbjohnson/litestream · error

detect page size: %w

Error message

detect page size: %w

What it means

Raised during VFSFile.Open when the page size could not be determined from the replica's LTX file infos. detectPageSizeFromInfos inspects the latest LTX file (header or index) to learn the database page size, which is required before the page cache and index can be built. A failure here aborts opening the database-backed VFS file.

Source

Thrown at vfs.go:1123

func (f *VFSFile) Open() error {
	f.logger.Debug("opening file")

	// Try to get restore plan. For write-enabled VFS, we can create a new database
	// if no LTX files exist yet.
	infos, err := f.waitForRestorePlan()
	if err != nil {
		// If write mode is enabled and no files exist, we can create a new database
		if f.writeEnabled && errors.Is(err, ErrTxNotAvailable) {
			f.logger.Info("no existing database found, creating new database")
			return f.openNewDatabase()
		}
		return err
	}

	pageSize, err := detectPageSizeFromInfos(f.ctx, f.client, infos)
	if err != nil {
		f.logger.Error("cannot detect page size", "error", err)
		return fmt.Errorf("detect page size: %w", err)
	}
	f.pageSize = pageSize

	// Initialize page cache. Convert byte size to number of pages.
	cacheEntries := f.CacheSize / int(pageSize)
	if cacheEntries < 1 {
		cacheEntries = 1
	}
	cache, err := lru.New[uint32, []byte](cacheEntries)
	if err != nil {
		return fmt.Errorf("create page cache: %w", err)
	}
	f.cache = cache

	// Determine the current position based off the latest LTX file.
	var pos ltx.Pos
	if len(infos) > 0 {
		pos = ltx.Pos{TXID: infos[len(infos)-1].MaxTXID}

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Verify the replica's LTX files are intact (litestream ltx -level all) and re-replicate from the primary if corrupt
2. Check replica client connectivity/credentials so LTX files can be read
3. Confirm both litestream versions are compatible; upgrade the reader to match the writer
4. Run litestream reset for the database if local LTX state is corrupted

infos, err := client.LTXInfos(ctx); if len(infos) == 0 || err != nil { /* fix replica before opening */ }

func replicaReadable(c vfs.ReplicaClient) bool { _, err := c.LTXInfos(context.Background()); return err == nil }

if err := file.Open(ctx); err != nil {
    if strings.Contains(err.Error(), "detect page size") {
        return fmt.Errorf("replica LTX unreadable/corrupt: %w", err)
    }
    return err
}

When it happens

Trigger: Opening a VFS file whose replica has unreadable/corrupt LTX infos: the latest LTX header is truncated, the file was written by an incompatible version, or reading from the replica client fails (network/permission error).

Common situations: Corrupted or partially-uploaded LTX files in the replica bucket; replica storage backend returning errors; opening a replica written by an older litestream with unexpected header layout.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

• cannot build index: %w
• no ltx file available to determine page size
• invalid replica, checksum mismatch
• open remote L0 file: %w
• encode ltx frame (pgno=%d): %w

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