benbjohnson/litestream · error

poll L1: %w

Error message

poll L1: %w

What it means

The VFS poll loop failed to fetch level-1 LTX files (pollLevel for compaction level 1) while merging level-0 and level-1 indexes. The replica listing errored — connectivity or credentials — so the read-only view cannot be advanced.

Source

Thrown at vfs.go:2630

		replaceIndex = true
		baseCommit = commit0
		newCommit = commit0
		combined = idx0
	} else {
		if len(idx0) > 0 {
			baseCommit = commit0
		}
		for k, v := range idx0 {
			combined[k] = v
		}
		if commit0 > newCommit {
			newCommit = commit0
		}
	}

	maxTXID1, idx1, commit1, replace1, err := f.pollLevel(ctx, 1, maxTXID1Snapshot, baseCommit)
	if err != nil {
		return fmt.Errorf("poll L1: %w", err)
	}
	if replace1 {
		replaceIndex = true
		baseCommit = commit1
		newCommit = commit1
		combined = idx1
	} else {
		for k, v := range idx1 {
			combined[k] = v
		}
		if commit1 > newCommit {
			newCommit = commit1
		}
	}

	// Send updates to a pending list if there are active readers.
	f.mu.Lock()
	defer f.mu.Unlock()

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Inspect the wrapped cause for the storage error detail
2. Verify the replica storage contains intact L1 prefixes and the client has access
3. Confirm object storage lifecycle rules are not deleting L1 files prematurely
4. Restart polling after transient failures; run `litestream reset` if local index state is inconsistent

iter, err := client.LTXFiles(ctx, 1, 1, false)
if err != nil {
    return fmt.Errorf("L1 storage unavailable: %w", err)
}
iter.Close()

if err := pollOnce(ctx); err != nil {
    if isRetryablePageError(err) { time.Sleep(backoff); return pollOnce(ctx) }
    return err
}

When it happens

Trigger: Background poll of L1 compaction files; client.LTXFiles(ctx, 1, ...) fails from storage errors, permission problems, or transient network conditions.

Common situations: Compaction-level prefixes misconfigured or deleted in object storage; IAM policies granting access to L0 but not L1 prefixes; storage outages.

Related errors

• poll L0: %w
• 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

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