unslothai/unsloth · error · ValueError

A reference is too large ({len(blob) / 1e6:.0f} MB); the lim

Error message

A reference is too large ({len(blob) / 1e6:.0f} MB); the limit is {_MAX_REFERENCE_MEDIA_BYTES / 1e6:.0f} MB.

What it means

The decoded reference blob exceeds _MAX_REFERENCE_MEDIA_BYTES = 96 MB (sized for roughly a 15-second reference clip). The limit is enforced after decode and before the media enters the pipeline, keeping oversized conditioning inputs from stalling generation or exhausting memory.

Source

Thrown at studio/backend/core/inference/video.py:425

def _decode_b64_media(data: Optional[str]) -> bytes:
    """Decode a base64 media payload, optionally wrapped in a data URL."""
    import base64
    import binascii

    raw = (data or "").strip()
    if not raw:
        raise ValueError("A reference was sent empty.")
    if raw.startswith("data:"):
        _, _, raw = raw.partition(",")
    try:
        blob = base64.b64decode(raw, validate = False)
    except (binascii.Error, ValueError) as exc:
        raise ValueError(f"Invalid base64 media data: {exc}") from exc
    if not blob:
        raise ValueError("A reference decoded to no data.")
    if len(blob) > _MAX_REFERENCE_MEDIA_BYTES:
        raise ValueError(
            f"A reference is too large ({len(blob) / 1e6:.0f} MB); the limit is "
            f"{_MAX_REFERENCE_MEDIA_BYTES / 1e6:.0f} MB."
        )
    return blob


class _VideoGenerationCancelled(Exception):
    """Unwinds a denoise loop that has no cooperative interrupt (no step callback);
    generate() maps it to the VIDEO_CANCELLED_MSG sentinel the routes 409 on."""


@contextlib.contextmanager
def _scheduler_step_progress(pipe: Any, on_step: Any):
    """Progress + cancellation for pipelines WITHOUT callback_on_step_end.

    HunyuanVideo15Pipeline exposes no per-step callback, but every denoise step
    makes exactly one ``scheduler.step`` call, so wrapping that method gives the
    same per-step tick the callback path gets. ``on_step`` receives the 1-based

View on GitHub (pinned to 203007d190)

Solutions

1. Trim the reference to ~15 seconds or less and re-encode at a moderate bitrate (H.264).
2. Downscale resolution; a 480-720p reference is usually sufficient for conditioning.
3. Re-encode PNG images to JPEG/WebP at reasonable quality to get under 96 MB decoded.

Example fix

# before
ref_b64 = encode(long_phone_video)  # 200 MB decoded -> rejected

# after
import ffmpeg  # trim + downscale first
ffmpeg.input('in.mp4').trim(end=15).filter('scale', 720, -2).output('ref.mp4').run()
ref_b64 = encode(open('ref.mp4','rb').read())

import base64
MAX_REF_BYTES = 96 * 1024 * 1024

def reference_within_limit(ref_b64: str) -> bool:
    raw = ref_b64.strip()
    if raw.startswith('data:'):
        raw = raw.partition(',')[2]
    decoded_len = (len(raw) * 3) // 4  # close upper-bound estimate
    return decoded_len <= MAX_REF_BYTES

try:
    result = generate_video(prompt=p, reference_video=ref)
except ValueError as e:
    if 'too large' in str(e):
        ref = trim_and_reencode(ref, max_seconds=15)
        result = generate_video(prompt=p, reference_video=ref)
    else:
        raise

When it happens

Trigger: Sending a reference video/image whose decoded byte size exceeds 96 MB — e.g. a 30-second 1080p clip, a PNG screenshot at very high resolution, or a minimally-compressed screen recording.

Common situations: Users dropping long phone videos as style references; uncompressed or PNG-sequence exports instead of H.264; believing the limit applies to the base64 length (it applies to the decoded bytes, which are ~3/4 of it).

Related errors

• A reference was sent empty.
• Invalid base64 media data: {exc}
• A reference decoded to no data.
• each reference must be at most 32 MiB (base64)
• Image is too large ({w}x{h}); maximum is {max_side}px per si

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