hiyouga/LlamaFactory · error · ValueError

`image_max_pixels` cannot be smaller than `image_min_pixels`

Error message

`image_max_pixels` cannot be smaller than `image_min_pixels`.

What it means

Raised in MultimodalArguments.__post_init__ (model_args.py:348) when image_max_pixels < image_min_pixels. These fields bound the resolution range used when rescaling input images for vision-language models; an empty range is contradictory and would make the resize logic pick undefined behavior, so it fails fast at config-parse time.

Source

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

        default=2.0,
        metadata={"help": "The frames to sample per second for video inputs."},
    )
    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(

View on GitHub (pinned to f28afaf635)

Solutions

1. Set image_max_pixels >= image_min_pixels (e.g. raise max or lower min)
2. If memory is the concern, lower BOTH bounds together, keeping max >= min
3. Remove both overrides to accept defaults

Example fix

# before
image_min_pixels: 112896   # 4*168*168
image_max_pixels: 65536

# after
image_min_pixels: 3136      # 4*28*28
image_max_pixels: 112896

assert cfg.get('image_max_pixels', INF_DEFAULT) >= cfg.get('image_min_pixels', 0), 'image pixel bounds inverted'

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

When it happens

Trigger: Setting image_max_pixels below image_min_pixels in one YAML (e.g. min 336*336 and max 262144); shrinking image_max_pixels to save memory without checking the default min (typically 4*28*28 for ViT-based models); overriding only one bound via CLI while the other stays at a conflicting default.

Common situations: Memory-tuning VLM preprocessing by lowering max pixels until it crosses the min; copying per-model examples that assume different defaults; unit confusion (pixels vs. pixels-per-side).

Related errors

• `video_max_pixels` cannot be smaller than `video_min_pixels`
• `virtual_pipeline_model_parallel_size` must be >= 1 when set
• `sequence_parallel` requires `tensor_model_parallel_size` >
• Please provide `model_name_or_path`.
• YAML config must be a dictionary mapping tokens to descripti

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