hiyouga/LlamaFactory · error · ValueError

`video_max_pixels` cannot be smaller than `video_min_pixels`

Error message

`video_max_pixels` cannot be smaller than `video_min_pixels`.

What it means

Raised in MultimodalArguments.__post_init__ (model_args.py:351) when video_max_pixels < video_min_pixels. Same invariant as the image pair but for video frames: the min/max pixel bounds for video preprocessing must form a non-empty range. Validated immediately when the multimodal dataclass is constructed.

Source

Thrown at src/llamafactory/hparams/model_args.py:351

    video_maxlen: int = field(
        default=128,
        metadata={"help": "The maximum number of sampled frames for video inputs."},
    )
    use_audio_in_video: bool = field(
        default=False,
        metadata={"help": "Whether or not to use audio in video inputs."},
    )
    audio_sampling_rate: int = field(
        default=16000,
        metadata={"help": "The sampling rate of audio inputs."},
    )

    def __post_init__(self):
        if self.image_max_pixels < self.image_min_pixels:
            raise ValueError("`image_max_pixels` cannot be smaller than `image_min_pixels`.")

        if self.video_max_pixels < self.video_min_pixels:
            raise ValueError("`video_max_pixels` cannot be smaller than `video_min_pixels`.")


@dataclass
class ExportArguments:
    r"""Arguments pertaining to the model export."""

    export_dir: str | None = field(
        default=None,
        metadata={"help": "Path to the directory to save the exported model."},
    )
    export_size: int = field(
        default=5,
        metadata={"help": "The file shard size (in GB) of the exported model."},
    )
    export_device: Literal["cpu", "auto"] = field(
        default="cpu",
        metadata={"help": "The device used in model export, use `auto` to accelerate exporting."},
    )

View on GitHub (pinned to f28afaf635)

Solutions

1. Ensure video_max_pixels >= video_min_pixels; adjust the pair together
2. To cut video memory, also lower video_min_pixels or reduce video_max_frames / fps instead of crossing the bounds
3. Remove both keys to fall back to defaults

Example fix

# before
video_min_pixels: 12845056  # 16384*28*28
video_max_pixels: 100352

# after
video_min_pixels: 100352    # 128*28*28
video_max_pixels: 737280     # 960*28*28

assert cfg.get('video_max_pixels', INF_DEFAULT) >= cfg.get('video_min_pixels', 0), 'video pixel bounds inverted'

def video_bounds_ok(mn: int, mx: int) -> bool:
    return mx >= mn

When it happens

Trigger: Setting video_max_pixels: 16384 with the default/overridden video_min_pixels higher than that; tuning long-video memory by cutting video_max_pixels below the min; overriding one bound in an accelerate launch --*overrides style CLI merge.

Common situations: Video-LLM experiments with aggressive frame-resolution caps; configs assembled from multiple includes where mins come from a shared base file; per-model recipes (Qwen-VL vs InternVL) using different default bounds mixed together.

Related errors

• `image_max_pixels` cannot be smaller than `image_min_pixels`
• This model does not support video input. Please check whethe
• The number of videos does not match the number of {VIDEO_PLA
• Invalid image found in video frames.
• MOSS-VL encountered nested video token blocks after tokeniza

AI-assisted analysis of hiyouga/LlamaFactory@f28afaf635 (2026-08-14). Data as JSON: /api/errors/7acb7b259229cf9b. Report an issue: GitHub.