invoke-ai/InvokeAI · error · ValueError

The requested transition needs an estimated {estimated_mib:.

Error message

The requested transition needs an estimated {estimated_mib:.0f} MiB, which exceeds the {limit_mib:.0f} MiB transition memory budget. Lower transition_frames or use lower-resolution clips.

What it means

Thrown by _validate_transition_memory when the estimated RAM needed to hold crossfade transition frames exceeds MAX_TRANSITION_MEMORY_BYTES. The estimate scales with clip width, height, and transition_frames, so high-resolution clips or large transition windows blow the budget. The library fails fast instead of being killed by OOM.

Source

Thrown at invokeai/app/invocations/video_concat.py:209

            return float(self.fps)
        known_rates = [rate for rate in source_rates if rate is not None and rate > 0]
        if not known_rates:
            return 16.0
        if any(not math.isclose(rate, known_rates[0], rel_tol=1e-3) for rate in known_rates[1:]):
            raise ValueError("Input videos have different frame rates; set Output FPS to retime them.")
        # An unknown rate mixed with agreeing known ones is not an error: probe_video
        # deliberately reports None for metadata-poor containers (VFR flags, missing
        # avg_frame_rate) whose real rate is usually the same as their neighbours'.
        # Erroring here would break previously-working concat workflows over a metadata
        # quirk; disagreement between *known* rates is the case that silently retimes.
        return known_rates[0]

    def _validate_transition_memory(self, width: int, height: int) -> None:
        estimated_bytes = self._estimate_transition_memory(width, height)
        if estimated_bytes > MAX_TRANSITION_MEMORY_BYTES:
            estimated_mib = estimated_bytes / (1024 * 1024)
            limit_mib = MAX_TRANSITION_MEMORY_BYTES / (1024 * 1024)
            raise ValueError(
                f"The requested transition needs an estimated {estimated_mib:.0f} MiB, "
                f"which exceeds the {limit_mib:.0f} MiB transition memory budget. "
                "Lower transition_frames or use lower-resolution clips."
            )

    def _iter_joined_frames(
        self,
        clips: list[Iterable[np.ndarray]],
        is_canceled: Optional[Callable[[], bool]] = None,
    ) -> Iterator[np.ndarray]:
        """Yields the joined output frames, pulling lazily from each clip's frame iterator.

        A frame is emitted as soon as it can no longer participate in a transition, so at
        most one transition window (the previous clip's tail plus the current clip's head,
        each bounded by ``transition_frames``) is buffered at a time — never a whole clip.

        Transition layout matches the class docstring:

View on GitHub (pinned to 0b6a024f2f)

Solutions

  1. Reduce the transition_frames field on the invocation
  2. Use lower-resolution clips (downscale inputs before concat)
  3. Lower width/height by pre-scaling the video files
  4. Increase MAX_TRANSITION_MEMORY_BYTES if the machine has enough RAM

Example fix

// before
vc = VideoConcat(videos=clips, transition_frames=60)  # 1080p clips, 4096 MiB budget exceeded
// after
vc = VideoConcat(videos=clips, transition_frames=15)  # fits budget
Defensive patterns

Strategy: validation

Validate before calling

est_mib = (width * height * transition_frames * 4) / (1024*1024)
if est_mib > 4096:
    raise ValueError('transition memory budget exceeded; lower transition_frames')

Try / catch

try:
    out = invocation.invoke(context)
except ValueError as e:
    if 'transition memory budget' in str(e):
        transition_frames = max(1, transition_frames // 2)
        out = rebuild_invocation(transition_frames).invoke(context)
    else:
        raise

Prevention

When it happens

Trigger: Calling invoke() on a VideoConcat invocation where _estimate_transition_memory(width, height) = f(width*height*transition_frames) exceeds MAX_TRANSITION_MEMORY_BYTES.

Common situations: Users concat 1080p/4K clips with large transition_frames values; budget default sized for 720p; misconfigured MAX_TRANSITION_MEMORY_BYTES constant too small.

Related errors

AI-assisted analysis of invoke-ai/InvokeAI@0b6a024f2f (2026-08-29). Data as JSON: /api/errors/5dcbaf58a6bde07c. Report an issue: GitHub.