invoke-ai/InvokeAI · error · ValueError

Decoded frame dimensions {width}x{height} exceed the maximum

Error message

Decoded frame dimensions {width}x{height} exceed the maximum decodable size

What it means

_validate_decoded_frame enforces MAX_FRAME_PIXELS on decoded frames and rejects non-positive dimensions. A decoded frame larger than the pixel budget would blow the parent's memory bound, so it is rejected here as a last line of defense after the pre-decode probe check.

Source

Thrown at invokeai/app/util/video_decode_worker.py:74

        import os
        import resource

        pages = int(Path("/proc/self/statm").read_text().split()[0])
        limit = pages * os.sysconf("SC_PAGE_SIZE") + WORKER_MEMORY_HEADROOM_BYTES
        _soft, hard = resource.getrlimit(resource.RLIMIT_AS)
        if hard != resource.RLIM_INFINITY:
            limit = min(limit, hard)
        resource.setrlimit(resource.RLIMIT_AS, (limit, hard))
    except (OSError, ValueError):
        pass


def _validate_decoded_frame(frame: np.ndarray) -> None:
    if frame.ndim != 3 or frame.shape[2] != 3:
        raise ValueError(f"Decoded frame must be RGB; got shape {frame.shape}")
    height, width = frame.shape[:2]
    if height <= 0 or width <= 0 or height * width > MAX_FRAME_PIXELS:
        raise ValueError(f"Decoded frame dimensions {width}x{height} exceed the maximum decodable size")


def _assert_decodable_dims(video_path: Path) -> None:
    """Refuses to decode frames from a video whose reported dimensions exceed the bound.

    If the dimensions cannot be probed, decoding is refused because the parent's frame
    record bound and PIL checks run only after the decoder has allocated the frame.
    """
    try:
        width, height, _duration, _fps = _probe(video_path)[:4]
    except Exception as error:
        raise ValueError(f"Unable to validate video dimensions for {video_path}") from error
    if width <= 0 or height <= 0:
        raise ValueError(f"Video reports invalid dimensions {width}x{height}")
    if width * height > MAX_FRAME_PIXELS:
        raise ValueError(f"Video dimensions {width}x{height} exceed the maximum decodable size")

View on GitHub (pinned to 0b6a024f2f)

Solutions

Downscale the video before decoding (e.g. ffmpeg -vf scale=...) to fit within MAX_FRAME_PIXELS
Crop or re-encode the source video to smaller dimensions
Account for rotation metadata by checking the frame after any auto-rotation, not just probe dimensions

Example fix

// before
ffmpeg -i input.mov -c copy output.mov  # keeps 16K dimensions

// after
ffmpeg -i input.mov -vf "scale='min(3840,iw)':-2" output.mov  # cap decoded width

Defensive patterns

Strategy: validation

Validate before calling

def frame_in_budget(f: np.ndarray) -> bool:
    h, w = f.shape[:2]
    return h > 0 and w > 0 and h * w <= MAX_FRAME_PIXELS

Type guard

def frame_in_budget(f: np.ndarray) -> bool:
    h, w = f.shape[:2]
    return bool(h > 0 and w > 0 and h * w <= MAX_FRAME_PIXELS)

Try / catch

try:
    _validate_decoded_frame(frame)
except ValueError as e:
    if "exceed the maximum decodable size" in str(e):
        frame = cv2.resize(frame, (frame.shape[1] // 2, frame.shape[0] // 2))
    else:
        raise

Prevention

Pre-decode probe dimensions and reject oversized sources (the worker already does this)
Re-encode large sources with an ffmpeg scale filter before processing
Mind rotation metadata: probed dims may differ from decoded frame dims
Keep MAX_FRAME_PIXELS aligned with your memory budget

When it happens

Trigger: A video whose probed dimensions passed but whose actually decoded frame is larger (e.g. rotated video where stored dimensions differ from display dimensions, or a probe that under-reported size).

Common situations: Rotated phone videos with rotation metadata (probed WxH swapped versus decoded frame); corrupt metadata in the container; very high-resolution (8K) source videos exceeding the pixel limit.

Related errors

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