benbjohnson/litestream · error

max ltx file: %w

Error message

max ltx file: %w

What it means

calcPos determines the replica's level-0 position by querying the storage client for metadata about the newest LTX file (MaxLTXFileInfo). If that query fails, this error wraps it. Note that a 'no files found' condition is typically not an error — this error means the metadata lookup itself failed against the remote replica.

Source

Thrown at replica.go:277

	}
	r.Logger().Debug("ltx file uploaded",
		"level", info.Level,
		"minTXID", info.MinTXID,
		"maxTXID", info.MaxTXID,
		"size", info.Size)

	// Track current position
	//replicaWALIndexGaugeVec.WithLabelValues(r.db.Path(), r.Name()).Set(float64(rd.Pos().Index))
	//replicaWALOffsetGaugeVec.WithLabelValues(r.db.Path(), r.Name()).Set(float64(rd.Pos().Offset))

	return nil
}

// calcPos returns the last position saved to the replica for level 0.
func (r *Replica) calcPos(ctx context.Context) (pos ltx.Pos, err error) {
	info, err := r.MaxLTXFileInfo(ctx, 0)
	if err != nil {
		return pos, fmt.Errorf("max ltx file: %w", err)
	}
	return ltx.Pos{TXID: info.MaxTXID}, nil
}

// MaxLTXFileInfo returns metadata about the last LTX file for a given level.
// Returns nil if no files exist for the level.
func (r *Replica) MaxLTXFileInfo(ctx context.Context, level int) (info ltx.FileInfo, err error) {
	// Normal operation - use fast timestamps
	itr, err := r.Client.LTXFiles(ctx, level, 0, false)
	if err != nil {
		return info, err
	}
	defer itr.Close()

	for itr.Next() {
		item := itr.Item()
		if item.MaxTXID > info.MaxTXID {
			info = *item

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Check the wrapped cause for the storage-client error and fix connectivity/permissions.
2. Verify the replica client config (bucket, prefix, endpoint) points at the right location.
3. Confirm the storage credentials allow listing LTX objects at level 0.
4. Retry; if the replica was freshly created with no backups, ensure your client version handles the empty case without erroring.

// verify listing access to level-0 LTX path before status/sync
infos, err := client.ListLTXFiles(ctx, 0)
if err != nil {
    return fmt.Errorf("replica storage unreachable: %w", err)
}

pos, err := replica.CalcPos(ctx) // or SyncStatus
if err != nil && strings.Contains(err.Error(), "max ltx file") {
    // storage listing failed: check wrapped cause, retry with backoff
}

When it happens

Trigger: Replica.SyncStatus or syncOnce calls calcPos, and r.MaxLTXFileInfo(ctx, 0) returns an error — the storage list/read operation fails (network error, auth failure, unexpected listing response).

Common situations: Cloud storage temporarily unreachable; IAM permissions missing for listing objects; misconfigured bucket path; storage client returning an unexpected response shape for an empty/new replica.

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

• replica sync: %w
• fetch ltx files: %w
• cannot determine L%d max ltx file for %q: %w
• max retries exceeded reading ltx file (level=%d, min=%s, max
• write ltx file: %w

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