unslothai/unsloth · error · ValueError

A reference was sent empty.

Error message

A reference was sent empty.

What it means

_decode_b64_media refuses a reference image/video whose payload is empty after stripping whitespace (the None-safe '(data or '')' also covers a missing field). This validates reference media (image-to-video / video-to-video conditioning inputs) before any decode work. An empty reference is always a client-side payload bug, never a server condition.

Source

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

        arch = (read_gguf_general_metadata(str(path)) or {}).get("general.architecture")
        return arch.strip() if isinstance(arch, str) and arch.strip() else None
    except Exception:  # noqa: BLE001 -- a header read glitch just falls through to name detection
        return None


# Enough for a 15-second reference video after base64 decoding.
_MAX_REFERENCE_MEDIA_BYTES = 96 * 1024 * 1024


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);

View on GitHub (pinned to 203007d190)

Solutions

1. Send the actual base64 payload (optionally as a data: URL) or omit the reference field entirely if the generation mode does not need one.
2. Guard in the caller: skip the request when the reference string is empty after trim.
3. Log the reference length client-side before sending.

Example fix

# before
payload = {'prompt': p, 'reference_image': ref_b64 or ''}

# after
payload = {'prompt': p}
if ref_b64 and ref_b64.strip():
    payload['reference_image'] = ref_b64

def has_reference(ref: str | None) -> bool:
    return bool(ref and ref.strip())

def is_nonempty_reference(ref: str | None) -> bool:
    return ref is not None and len(ref.strip()) > 0

try:
    result = generate_video(prompt=p, reference_image=ref)
except ValueError as e:
    if 'reference was sent empty' in str(e):
        result = generate_video(prompt=p)  # no reference
    else:
        raise

When it happens

Trigger: Calling video generation with a reference field of '', ' ', or None/omitted after JSON defaults — e.g. a data URL that lost its base64 part or a form field that was never filled.

Common situations: Frontend sends the key with an empty string when the user attaches nothing; a data-URL builder returns 'data:image/png,' and the payload gets stripped; upstream code passes an unset optional straight through.

Related errors

• Invalid base64 media data: {exc}
• A reference decoded to no data.
• A reference is too large ({len(blob) / 1e6:.0f} MB); the lim
• each reference must be at most 32 MiB (base64)
• Unknown model_kind '{model_kind}'. Expected one of {sorted(_

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