invalid ltx file: level=%d min=%s max=%s has size %d bytes (

Error message

invalid ltx file: level=%d min=%s max=%s has size %d bytes (minimum %d)

What it means

Restore found an LTX file in the plan whose size is below ltx.HeaderSize, so its header cannot even be read. The remote file is truncated or corrupted (partial upload), making the restore chain unusable at that file.

Source

Thrown at replica.go:705

	if err != nil {
		return fmt.Errorf("cannot calc restore plan: %w", err)
	}

	r.Logger().Debug("restore plan", "n", len(infos), "txid", infos[len(infos)-1].MaxTXID, "timestamp", infos[len(infos)-1].CreatedAt)

	rdrs := make([]io.Reader, 0, len(infos))
	defer func() {
		for _, rd := range rdrs {
			if closer, ok := rd.(io.Closer); ok {
				_ = closer.Close()
			}
		}
	}()

	for _, info := range infos {
		// Validate file size - must be at least header size to be readable
		if info.Size < ltx.HeaderSize {
			return fmt.Errorf("invalid ltx file: level=%d min=%s max=%s has size %d bytes (minimum %d)",
				info.Level, info.MinTXID, info.MaxTXID, info.Size, ltx.HeaderSize)
		}

		r.Logger().Debug("opening ltx file for restore", "level", info.Level, "min", info.MinTXID, "max", info.MaxTXID)

		rdrs = append(rdrs, internal.NewResumableReader(ctx, r.Client, info.Level, info.MinTXID, info.MaxTXID, info.Size, nil, r.Logger()))
	}

	if len(rdrs) == 0 {
		return fmt.Errorf("no matching backup files available")
	}

	// Create parent directory if it doesn't exist.
	var dirInfo os.FileInfo
	if db := r.DB(); db != nil {
		dirInfo = db.dirInfo
	}
	if err := internal.MkdirAll(filepath.Dir(opt.OutputPath), dirInfo); err != nil {

View on GitHub (pinned to 4ed7a308f6)

Solutions

Delete the truncated LTX object from the replica and force re-upload of that range
Run 'litestream ltx' to inspect replica file sizes and locate corruption

Defensive patterns

Strategy: validation

When it happens

Trigger: Thrown at replica.go:705 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/5c8a9c8ae5b56b58. Report an issue: GitHub.