invoke-ai/InvokeAI · error · ValueError

Unable to validate video dimensions for {video_path}

Error message

Unable to validate video dimensions for {video_path}

What it means

_assert_decodable_dims probes a video's dimensions before decoding so oversized frames are rejected before the decoder allocates memory. If the probe itself throws for any reason, the function refuses to decode rather than risk an unbounded frame allocation, wrapping the underlying error in this ValueError (original chained via __cause__).

Source

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

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")


def _extract_frame(video_path: Path, frame_index: int) -> Optional[Image.Image]:
    """Extracts a single frame from a video file as a PIL Image. Returns None on failure.

    Tries imageio's FFMPEG plugin first since it's the same encoder we use for output,
    then falls back to cv2 — uploaded videos with unusual codecs may need that path.
    """
    try:
        # iio.imread with index=N seeks to that frame directly. Returns RGB HxWxC uint8.
        frame = iio.imread(video_path, plugin="FFMPEG", index=frame_index)
        _validate_decoded_frame(frame)
        return Image.fromarray(frame)
    except Exception:

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Inspect the chained cause (err.__cause__) to find the actual probe failure
2. Repair/re-encode the file (e.g. ffmpeg -i bad.mp4 -c copy fixed.mp4) or re-download it
3. Check file permissions and that the path points to a complete video file
4. Verify the codec is supported by the installed OpenCV/FFmpeg build

import subprocess
def probe_ok(path) -> bool:
    r = subprocess.run(["ffprobe", "-v", "error", str(path)], capture_output=True)
    return r.returncode == 0

try:
    _assert_decodable_dims(video_path)
except ValueError as e:
    logger.error("dimension probe failed for %s: cause=%r", video_path, e.__cause__)
    # mark file undecodable / skip

When it happens

Trigger: cv2 failing to read metadata from a corrupt/truncated file, an unsupported codec, a partially downloaded file, or any exception inside _probe other than the is-opened failure (which raises FileNotFoundError instead).

Common situations: Broken or incomplete video files; exotic codecs OpenCV's FFmpeg build can't probe; permission or I/O errors mid-read; zero-byte placeholder files.

Related errors

• Video reports invalid dimensions {width}x{height}
• Video has no decodable frame
• video_concat requires at least two input videos.
• All inputs must share the same dimensions. Got: {sorted(widt
• The requested transition needs an estimated {estimated_mib:.

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