benbjohnson/litestream · error

no matching backup files available

Error message

no matching backup files available

What it means

Guard in Replica.Restore when the iterator of LTX files from the replica client yielded no usable files to apply. Fires when the replica contains no LTX files matching the restore criteria, so there is no backup data from which to reconstruct the database.

Source

Thrown at replica.go:715

				_ = 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 {
		return fmt.Errorf("create parent directory: %w", err)
	}

	// Output to temp file & atomically rename.
	tmpOutputPath := opt.OutputPath + ".tmp"
	r.Logger().Debug("compacting into database", "path", tmpOutputPath, "n", len(rdrs))
	defer func() { _ = os.Remove(tmpOutputPath) }()

	f, err := os.Create(tmpOutputPath)
	if err != nil {

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Verify the replica actually contains LTX files (litestream ltx)
2. Relax the -timestamp/-txid filter to match available history
3. Take a fresh backup if the replica is empty

When it happens

Trigger: Thrown at replica.go:715 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/88cf769f49dc1eed. Report an issue: GitHub.