{"record":{"id":"f83629d507e9b4cc","repo":"invoke-ai/InvokeAI","slug":"video-dimensions-width-x-height-exceed-the-maxim","errorCode":null,"errorMessage":"Video dimensions {width}x{height} exceed the maximum decodable size","messagePattern":"Video dimensions (.+?)x(.+?) exceed the maximum decodable size","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"invokeai/app/util/video_decode_worker.py","lineNumber":90,"sourceCode":"    height, width = frame.shape[:2]\n    if height <= 0 or width <= 0 or height * width > MAX_FRAME_PIXELS:\n        raise ValueError(f\"Decoded frame dimensions {width}x{height} exceed the maximum decodable size\")\n\n\ndef _assert_decodable_dims(video_path: Path) -> None:\n    \"\"\"Refuses to decode frames from a video whose reported dimensions exceed the bound.\n\n    If the dimensions cannot be probed, decoding is refused because the parent's frame\n    record bound and PIL checks run only after the decoder has allocated the frame.\n    \"\"\"\n    try:\n        width, height, _duration, _fps = _probe(video_path)[:4]\n    except Exception as error:\n        raise ValueError(f\"Unable to validate video dimensions for {video_path}\") from error\n    if width <= 0 or height <= 0:\n        raise ValueError(f\"Video reports invalid dimensions {width}x{height}\")\n    if width * height > MAX_FRAME_PIXELS:\n        raise ValueError(f\"Video dimensions {width}x{height} exceed the maximum decodable size\")\n\n\ndef _extract_frame(video_path: Path, frame_index: int) -> Optional[Image.Image]:\n    \"\"\"Extracts a single frame from a video file as a PIL Image. Returns None on failure.\n\n    Tries imageio's FFMPEG plugin first since it's the same encoder we use for output,\n    then falls back to cv2 — uploaded videos with unusual codecs may need that path.\n    \"\"\"\n    try:\n        # iio.imread with index=N seeks to that frame directly. Returns RGB HxWxC uint8.\n        frame = iio.imread(video_path, plugin=\"FFMPEG\", index=frame_index)\n        _validate_decoded_frame(frame)\n        return Image.fromarray(frame)\n    except Exception:\n        pass\n\n    try:\n        import cv2  # local import so the imageio-only path doesn't pay the cv2 import cost","sourceCodeStart":72,"sourceCodeEnd":108,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/app/util/video_decode_worker.py#L72-L108","documentation":"If probed width*height exceeds MAX_FRAME_PIXELS, the video is refused before decoding. This pre-decode check exists because the decoder allocates the full frame buffer, which the parent's frame-record bound and PIL checks only see after allocation — too late to prevent the memory spike.","triggerScenarios":"Decoding any video whose reported WxH product is above MAX_FRAME_PIXELS — e.g. 8K+ (7680x4320 ~33MP) or other very large sources — via main/_extract_frame paths that call _assert_decodable_dims.","commonSituations":"8K/12K source footage; panorama or stitched videos; users pointing the worker at raw camera outputs.","solutions":["Re-encode the video to smaller dimensions (ffmpeg -vf scale=...) within the pixel budget","Extract frames with a downscaling filter or a different tool and feed the worker the reduced video","If the limit is too strict for your workload, raise MAX_FRAME_PIXELS consciously with the memory implications in mind"],"exampleFix":"// before\nffmpeg -i 8k_input.mp4 -c copy small.mp4  # stream copy keeps 8K\n\n// after\nffmpeg -i 8k_input.mp4 -vf scale=3840:-2 small.mp4  # fits within pixel budget","handlingStrategy":"validation","validationCode":"import cv2\ndef within_budget(path) -> bool:\n    cap = cv2.VideoCapture(str(path))\n    if not cap.isOpened():\n        return False\n    w, h = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH)), int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))\n    cap.release()\n    return w * h <= MAX_FRAME_PIXELS","typeGuard":"def within_budget(w: int, h: int) -> bool:\n    return 0 < w and 0 < h and w * h <= MAX_FRAME_PIXELS","tryCatchPattern":"try:\n    _assert_decodable_dims(video_path)\nexcept ValueError as e:\n    if \"exceed the maximum decodable size\" in str(e):\n        video_path = downscale_video(video_path)  # ffmpeg -vf scale=...\n    else:\n        raise","preventionTips":["Downscale 8K+/panorama sources with ffmpeg before processing","Document the pixel budget for users submitting source videos","If larger frames are legitimately needed, raise MAX_FRAME_PIXELS with memory sizing in mind","Check both probe dims and decoded frame dims (rotation can swap them)"],"tags":["video","resource-limit","validation","ffmpeg"],"backgroundTag":"video-resolution-too-large","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}