benbjohnson/litestream · error

fetch l0 files: %w

Error message

fetch l0 files: %w

What it means

EnforceL0Retention lists level-0 (L0, transactional) LTX files to find those older than the retention threshold. Failure to open that listing iterator is wrapped as 'fetch l0 files: %w'. No L0 files are deleted when this fails.

Source

Thrown at compactor.go:370

	}
	var maxL1TXID ltx.TXID
	for itr.Next() {
		info := itr.Item()
		if info.MaxTXID > maxL1TXID {
			maxL1TXID = info.MaxTXID
		}
	}
	if err := itr.Close(); err != nil {
		return fmt.Errorf("close l1 iterator: %w", err)
	}
	if maxL1TXID == 0 {
		return nil
	}

	threshold := time.Now().Add(-retention)
	itr, err = c.client.LTXFiles(ctx, 0, 0, false)
	if err != nil {
		return fmt.Errorf("fetch l0 files: %w", err)
	}
	defer itr.Close()

	var (
		deleted      []*ltx.FileInfo
		lastInfo     *ltx.FileInfo
		processedAll = true
	)
	for itr.Next() {
		info := itr.Item()
		lastInfo = info

		createdAt := info.CreatedAt
		if createdAt.IsZero() {
			createdAt = threshold
		}

		if createdAt.After(threshold) {

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Verify credentials have list access to the level-0 path in the replica
2. Check provider status/endpoint reachability; retry the periodic retention run
3. Confirm replica path configuration matches where L0 files are written
4. Inspect the wrapped error's provider code for the precise cause

// Health-check the storage backend before the retention window
ctx, cancel := context.WithTimeout(ctx, 10*time.Second)
defer cancel()
_, err := client.LTXFiles(ctx, 0, 0, false)

if err := c.EnforceL0Retention(ctx, retention); err != nil {
    if isTransientStorageError(err) { /* backoff and retry next cycle */ }
}

When it happens

Trigger: c.client.LTXFiles(ctx, 0, 0, false) fails after the L1 watermark check succeeded — storage auth error, endpoint outage, or listing API failure on the level-0 prefix.

Common situations: S3/GCS outage; expired session token mid-cycle; bucket path renamed so the l0/ prefix no longer matches; per-prefix IAM scoping missing the transactional file path.

Related errors

• fetch l1 files: %w
• close l1 iterator: %w
• fetch l0 files: %w
• abs: cannot delete ltx file %q: %w
• abs: cannot list blobs: %w

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