unslothai/unsloth · error · ValueError

Image is too large ({w}x{h}); maximum is {max_side}px per si

Error message

Image is too large ({w}x{h}); maximum is {max_side}px per side.

What it means

Raised by the image header check in the diffusion module: the decoded PIL image's width or height exceeds max_side (4096px), rejected before img.load() so a huge-dimension decompression bomb cannot spike memory. The 4096px bound deliberately covers txt2img 2048 plus upscale/outpaint canvases.

Source

Thrown at studio/backend/core/inference/diffusion.py:383

    from PIL import Image

    raw = data.strip()
    if raw.startswith("data:"):
        # data:[<mime>][;base64],<payload>
        _, _, raw = raw.partition(",")
    try:
        blob = base64.b64decode(raw, validate = False)
    except (binascii.Error, ValueError) as exc:
        raise ValueError(f"Invalid base64 image data: {exc}") from exc
    # Bound the decoded size: 4096px covers txt2img 2048, upscales and outpaint canvases.
    max_side = 4096
    try:
        img = Image.open(io.BytesIO(blob))
        # Reject from the header before img.load() so a huge-dimension file cannot spike memory.
        w, h = img.size
        if w > max_side or h > max_side:
            raise ValueError(f"Image is too large ({w}x{h}); maximum is {max_side}px per side.")
        img.load()
    except ValueError:
        raise  # the size guard's own message; don't wrap it as a decode error
    except Exception as exc:  # noqa: BLE001 — surfaced as a 400 to the client
        raise ValueError(f"Could not decode image: {exc}") from exc
    return img.convert(mode)


def _snap_to_multiple(img: Any, multiple: int = 16) -> Any:
    """Resize a PIL image so both sides are multiples of ``multiple`` (rounded to nearest,
    minimum one multiple), preserving content with a high-quality resample.

    Image-conditioned pipelines (Z-Image / Qwen / FLUX: 8x VAE downsample + 2x patch) reject
    sizes that are not divisible by 16. Rather than error on an odd-sized upload, snap it so
    the workflow just works; rounding to nearest keeps the rescale minimal/accurate."""
    from PIL import Image

    w, h = img.size

View on GitHub (pinned to 203007d190)

Solutions

1. Downscale the image to ≤4096px on the longest side before uploading (any image editor or PIL thumbnail)
2. If you legitimately need bigger canvases, crop/outpaint in ≤4096 tiles
3. Do not bypass the guard by editing max_side — it exists to bound decode memory

Example fix

# client-side, before upload
from PIL import Image
img = Image.open("photo.jpg")
img.thumbnail((4096, 4096))
img.save("photo_small.jpg")

MAX_SIDE = 4096
def within_size_limit(w: int, h: int) -> bool:
    return w <= MAX_SIDE and h <= MAX_SIDE

def prepared_image(path: str):
    from PIL import Image
    img = Image.open(path)
    if img.width > MAX_SIDE or img.height > MAX_SIDE:
        img.thumbnail((MAX_SIDE, MAX_SIDE))
    return img

try:
    img = parse_b64_image(data)
except ValueError as e:
    if "too large" in str(e):
        return JSONResponse(status_code=422, content={"detail": str(e)})

When it happens

Trigger: Uploading a 6000×4000 photo for img2img; a PNG with large dimensions in its header (small file, huge decompressed size); upscaled scans; a canvas export at 8K.

Common situations: Phone/photo-library images at full resolution; print-quality scans; users assuming the server will downscale arbitrary inputs (it does for divisibility via _snap_to_multiple, not for the size cap).

Related errors

• Invalid base64 image data: {exc}
• Could not decode image: {exc}
• Unknown model_kind '{model_kind}'. Expected one of {sorted(_
• Local base_repo is not a diffusers pipeline directory (no {i
• a single-file checkpoint name is required for a '{kind}' loa

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