{"record":{"id":"86d325dbf11fa157","repo":"unslothai/unsloth","slug":"a-reference-was-sent-empty","errorCode":null,"errorMessage":"A reference was sent empty.","messagePattern":"A reference was sent empty\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"studio/backend/core/inference/video.py","lineNumber":415,"sourceCode":"\n        arch = (read_gguf_general_metadata(str(path)) or {}).get(\"general.architecture\")\n        return arch.strip() if isinstance(arch, str) and arch.strip() else None\n    except Exception:  # noqa: BLE001 -- a header read glitch just falls through to name detection\n        return None\n\n\n# Enough for a 15-second reference video after base64 decoding.\n_MAX_REFERENCE_MEDIA_BYTES = 96 * 1024 * 1024\n\n\ndef _decode_b64_media(data: Optional[str]) -> bytes:\n    \"\"\"Decode a base64 media payload, optionally wrapped in a data URL.\"\"\"\n    import base64\n    import binascii\n\n    raw = (data or \"\").strip()\n    if not raw:\n        raise ValueError(\"A reference was sent empty.\")\n    if raw.startswith(\"data:\"):\n        _, _, raw = raw.partition(\",\")\n    try:\n        blob = base64.b64decode(raw, validate = False)\n    except (binascii.Error, ValueError) as exc:\n        raise ValueError(f\"Invalid base64 media data: {exc}\") from exc\n    if not blob:\n        raise ValueError(\"A reference decoded to no data.\")\n    if len(blob) > _MAX_REFERENCE_MEDIA_BYTES:\n        raise ValueError(\n            f\"A reference is too large ({len(blob) / 1e6:.0f} MB); the limit is \"\n            f\"{_MAX_REFERENCE_MEDIA_BYTES / 1e6:.0f} MB.\"\n        )\n    return blob\n\n\nclass _VideoGenerationCancelled(Exception):\n    \"\"\"Unwinds a denoise loop that has no cooperative interrupt (no step callback);","sourceCodeStart":397,"sourceCodeEnd":433,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/inference/video.py#L397-L433","documentation":"_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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Send the actual base64 payload (optionally as a data: URL) or omit the reference field entirely if the generation mode does not need one.","Guard in the caller: skip the request when the reference string is empty after trim.","Log the reference length client-side before sending."],"exampleFix":"# before\npayload = {'prompt': p, 'reference_image': ref_b64 or ''}\n\n# after\npayload = {'prompt': p}\nif ref_b64 and ref_b64.strip():\n    payload['reference_image'] = ref_b64","handlingStrategy":"validation","validationCode":"def has_reference(ref: str | None) -> bool:\n    return bool(ref and ref.strip())","typeGuard":"def is_nonempty_reference(ref: str | None) -> bool:\n    return ref is not None and len(ref.strip()) > 0","tryCatchPattern":"try:\n    result = generate_video(prompt=p, reference_image=ref)\nexcept ValueError as e:\n    if 'reference was sent empty' in str(e):\n        result = generate_video(prompt=p)  # no reference\n    else:\n        raise","preventionTips":["Omit optional reference keys when there is no media rather than sending ''.","Assert non-empty payloads at the client boundary.","Build data URLs only from successfully-read blobs."],"tags":["video","reference-media","validation","payload"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}