benbjohnson/litestream · error

cannot calc restore plan: %w

Error message

cannot calc restore plan: %w

What it means

CalcRestorePlan failed while determining the sequence of snapshot+incremental LTX files needed to reach the requested TXID/timestamp. Causes: replica listing errors, no snapshot available at all, or a gap in TXID history around the requested point.

Source

Thrown at replica.go:688

	}

	// Compare v0.3.x and LTX formats to find the best backup (unless TXID is specified).
	// Skip V3 format when follow mode is enabled (V3 doesn't support incremental following).
	if opt.TXID == 0 && !opt.Follow {
		if client, ok := r.Client.(ReplicaClientV3); ok {
			useV3, err := r.shouldUseV3Restore(ctx, client, opt.Timestamp)
			if err != nil {
				return err
			}
			if useV3 {
				return r.RestoreV3(ctx, opt)
			}
		}
	}

	infos, err := CalcRestorePlan(ctx, r.Client, opt.TXID, opt.Timestamp, r.Logger())
	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)

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Verify backups exist for the requested point in time (litestream ltx)
2. Check replica connectivity and credentials
3. Pick an earlier timestamp whose history is still retained

When it happens

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