unslothai/unsloth · error · ValueError

MiniMax-H3 was trained on aspect ratios from 1:4 to 4:1; thi

Error message

MiniMax-H3 was trained on aspect ratios from 1:4 to 4:1; this clip is {aspect_width:g}x{aspect_height:g} ({ratio:.2f}:1). Crop it first.

What it means

Raised by the H3 canvas helper when the clip's aspect ratio falls outside H3_MIN_ASPECT_RATIO..H3_MAX_ASPECT_RATIO (1:4 to 4:1), the range MiniMax-H3 was trained on. The model has no representation for more extreme ratios, so the trainer requires the clip to be cropped first rather than silently training on out-of-distribution geometry.

Source

Thrown at studio/backend/core/training/diffusion_h3_clips.py:158

def h3_train_canvas(
    aspect_width: float,
    aspect_height: float,
    short_edge: int = H3_CANVAS_SHORT_EDGE,
    max_pixels: Optional[int] = None,
) -> tuple[int, int]:
    """MiniMax-H3's canvas rule, as ``(width, height)``.

    Identical arithmetic to the pipeline's ``resolve_canvas_size`` (which returns
    ``(height, width)``), re-expressed here so the trainer can size a dataset before any
    diffusers import. ``short_edge`` is the run's ``resolution``; the area cap scales with it
    so a smaller training canvas keeps the released aspect budget rather than the released
    pixel count.
    """
    if aspect_width <= 0 or aspect_height <= 0:
        raise ValueError(f"The aspect ratio must be positive, got {aspect_width}:{aspect_height}.")
    ratio = aspect_width / aspect_height
    if not H3_MIN_ASPECT_RATIO <= ratio <= H3_MAX_ASPECT_RATIO:
        raise ValueError(
            f"MiniMax-H3 was trained on aspect ratios from 1:4 to 4:1; this clip is "
            f"{aspect_width:g}x{aspect_height:g} ({ratio:.2f}:1). Crop it first."
        )
    if max_pixels is None:
        # The released cap, rescaled to the requested short edge: (1344/768) * short_edge^2.
        max_pixels = int(H3_CANVAS_MAX_PIXELS * (short_edge / H3_CANVAS_SHORT_EDGE) ** 2)
    if ratio >= 1.0:
        width, height = short_edge * ratio, float(short_edge)
    else:
        width, height = float(short_edge), short_edge / ratio
    area = width * height
    if area > max_pixels:
        scale = math.sqrt(max_pixels / area)
        width, height = width * scale, height * scale

    def snap(value: float) -> int:
        return max(H3_CANVAS_MULTIPLE, round(value / H3_CANVAS_MULTIPLE) * H3_CANVAS_MULTIPLE)

View on GitHub (pinned to 203007d190)

Solutions

1. Crop the clip to within 1:4..4:1 (center-crop the long edge) before adding it to the dataset.
2. Exclude the offending clip from the training set if cropping would destroy its content.
3. Add an aspect-ratio precheck during dataset ingestion so bad clips are reported by name.

Example fix

# before
w, h = h3_canvas_size(2048, 400, short_edge=768)  # 5.12:1 -> ValueError

# after
# center-crop width to at most 4x height first
crop_w = min(2048, 400 * 4)
w, h = h3_canvas_size(crop_w, 400, short_edge=768)

MIN_AR, MAX_AR = 1 / 4, 4.0

def aspect_trainable(w: int, h: int) -> bool:
    return MIN_AR <= w / h <= MAX_AR

When it happens

Trigger: Passing an aspect pair like 1000:200 (5:1) or a 9:16-vs-1:10 extreme — any ratio < 0.25 or > 4.0; ultra-wide screen recordings or tall phone videos beyond 4:1 mixed into a dataset.

Common situations: Datasets scraped from phone screenshots, cinematic ultra-wide crops, or split-screen captures; an automated pipeline that never checks aspect before training; letterboxed videos counted at full canvas ratio.

Related errors

• MiniMax-H3 supports aspect ratios from 1:4 to 4:1; this imag
• The aspect ratio must be positive, got {aspect_width}:{aspec
• {Path(path).name} carries no video track.
• {Path(path).name} carries no audio track. MiniMax-H3 denoise
• {Path(path).name} decoded to {len(frames)} frames at {H3_FPS

AI-assisted analysis of unslothai/unsloth@203007d190 (2026-08-15). Data as JSON: /api/errors/2d0c6341acc7ead5. Report an issue: GitHub.