benbjohnson/litestream · error

list level 0 ltx files: %w

Error message

list level 0 ltx files: %w

What it means

applyNewLTXFiles failed to obtain the level-0 LTX file listing from the replica (LTXFiles). Backend list error — connectivity, credentials, or bucket state — prevents the follow loop from seeing new transactions.

Source

Thrown at replica.go:871

				}
				r.Logger().Info("follow: applied updates", "from_txid", lastTXID, "to_txid", newTXID)
				lastTXID = newTXID
				consecutiveErrors = 0
			}
		}
	}
}

// applyNewLTXFiles polls for new LTX files and applies them to the database.
// It starts from level 0 and falls back to higher levels if there are gaps
// (e.g., level 0 files were compacted away).
func (r *Replica) applyNewLTXFiles(ctx context.Context, f *os.File, afterTXID ltx.TXID, pageSize uint32) (ltx.TXID, error) {
	currentTXID := afterTXID

	// Poll level 0 for the most recent incremental files.
	itr, err := r.Client.LTXFiles(ctx, 0, currentTXID+1, false)
	if err != nil {
		return currentTXID, fmt.Errorf("list level 0 ltx files: %w", err)
	}
	closeLevel0 := func(retErr error) (ltx.TXID, error) {
		if closeErr := itr.Close(); closeErr != nil {
			closeErr = fmt.Errorf("close level 0 ltx iterator: %w", closeErr)
			if retErr != nil {
				return currentTXID, errors.Join(retErr, closeErr)
			}
			return currentTXID, closeErr
		}
		return currentTXID, retErr
	}

	var sawLevel0 bool
	for itr.Next() {
		sawLevel0 = true
		info := itr.Item()

		// If there's a gap, try to fill it from higher compaction levels.

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Check replica backend connectivity and credentials
2. The follow loop tolerates repeated errors (logged with consecutive_errors) and keeps polling; fix the backend to resume applying

When it happens

Trigger: Thrown at replica.go:871 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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