{"record":{"id":"125022407ce4d261","repo":"unslothai/unsloth","slug":"a-reference-is-too-large-len-blob-1e6-0f-mb","errorCode":null,"errorMessage":"A reference is too large ({len(blob) / 1e6:.0f} MB); the limit is {_MAX_REFERENCE_MEDIA_BYTES / 1e6:.0f} MB.","messagePattern":"A reference is too large \\((.+?) MB\\); the limit is (.+?) MB\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"studio/backend/core/inference/video.py","lineNumber":425,"sourceCode":"\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);\n    generate() maps it to the VIDEO_CANCELLED_MSG sentinel the routes 409 on.\"\"\"\n\n\n@contextlib.contextmanager\ndef _scheduler_step_progress(pipe: Any, on_step: Any):\n    \"\"\"Progress + cancellation for pipelines WITHOUT callback_on_step_end.\n\n    HunyuanVideo15Pipeline exposes no per-step callback, but every denoise step\n    makes exactly one ``scheduler.step`` call, so wrapping that method gives the\n    same per-step tick the callback path gets. ``on_step`` receives the 1-based","sourceCodeStart":407,"sourceCodeEnd":443,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/inference/video.py#L407-L443","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["Trim the reference to ~15 seconds or less and re-encode at a moderate bitrate (H.264).","Downscale resolution; a 480-720p reference is usually sufficient for conditioning.","Re-encode PNG images to JPEG/WebP at reasonable quality to get under 96 MB decoded."],"exampleFix":"# before\nref_b64 = encode(long_phone_video)  # 200 MB decoded -> rejected\n\n# after\nimport ffmpeg  # trim + downscale first\nffmpeg.input('in.mp4').trim(end=15).filter('scale', 720, -2).output('ref.mp4').run()\nref_b64 = encode(open('ref.mp4','rb').read())","handlingStrategy":"validation","validationCode":"import base64\nMAX_REF_BYTES = 96 * 1024 * 1024\n\ndef reference_within_limit(ref_b64: str) -> bool:\n    raw = ref_b64.strip()\n    if raw.startswith('data:'):\n        raw = raw.partition(',')[2]\n    decoded_len = (len(raw) * 3) // 4  # close upper-bound estimate\n    return decoded_len <= MAX_REF_BYTES","typeGuard":null,"tryCatchPattern":"try:\n    result = generate_video(prompt=p, reference_video=ref)\nexcept ValueError as e:\n    if 'too large' in str(e):\n        ref = trim_and_reencode(ref, max_seconds=15)\n        result = generate_video(prompt=p, reference_video=ref)\n    else:\n        raise","preventionTips":["Trim reference videos to ~15 s and encode H.264 at moderate bitrate.","The limit applies to decoded bytes (~75% of the base64 length), not the string length.","Downscale images to the resolution the conditioning actually consumes."],"tags":["video","reference-media","size-limit","payload"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}