benbjohnson/litestream · error

list level 0 ltx files

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.

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.

Appendix: 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)