{"record":{"id":"c3bb9206888bdecb","repo":"unslothai/unsloth","slug":"each-reference-image-must-be-at-most-32-mib-base6","errorCode":null,"errorMessage":"each reference image must be at most 32 MiB (base64)","messagePattern":"each reference image must be at most 32 MiB \\(base64\\)","errorType":"validation","errorClass":"ValueError","httpStatus":422,"severity":"error","filePath":"studio/backend/models/inference.py","lineNumber":3064,"sourceCode":"        # Both apply paths suffix colliding adapter names, so a repeated id would load the SAME adapter twice and stack its effect past the weight bound.\n        if value:\n            seen: set[str] = set()\n            for spec in value:\n                if spec.id in seen:\n                    raise ValueError(\n                        f\"duplicate LoRA id '{spec.id}'; list each adapter at most once\"\n                    )\n                seen.add(spec.id)\n        return value\n\n    @field_validator(\"reference_images\")\n    @classmethod\n    def _bounded_reference_items(cls, value: Optional[list[str]]) -> Optional[list[str]]:\n        # Each reference is a base64 image; bound its length like init_image so several cannot buffer a multi-GB payload.\n        if value is not None:\n            for item in value:\n                if len(item) > 32 * 1024 * 1024:\n                    raise ValueError(\"each reference image must be at most 32 MiB (base64)\")\n        return value\n\n    @field_validator(\"width\", \"height\")\n    @classmethod\n    def _multiple_of_16(cls, value: int) -> int:\n        # Z-Image requires dimensions divisible by 16 (8x VAE downsample + 2x patch); non-multiples crash deep in the pipeline.\n        if value % 16 != 0:\n            raise ValueError(\"must be a multiple of 16\")\n        return value\n\n    @model_validator(mode = \"after\")\n    def _batch_seeds_json_safe(self) -> \"DiffusionGenerateRequest\":\n        # A batch derives seeds as seed..seed+batch_size-1, so a derived top-of-batch seed can exceed the 2**53-1 JSON-safe cap.\n        if self.seed is not None and self.seed + self.batch_size - 1 > 2**53 - 1:\n            raise ValueError(\n                \"seed + batch_size - 1 must not exceed 2**53 - 1 so every per-image seed \"\n                \"stays JSON-safe (lower the seed or the batch_size)\"\n            )","sourceCodeStart":3046,"sourceCodeEnd":3082,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/models/inference.py#L3046-L3082","documentation":"Raised by the reference_images field_validator on DiffusionGenerateRequest when any single base64 reference image string exceeds 32 MiB. The cap (mirroring init_image's max_length) stops one request from buffering a multi-GB payload in memory.","triggerScenarios":"Sending reference_images entries larger than 32*1024*1024 base64 characters — roughly a >24 MB raw image (base64 adds ~33% overhead), e.g. an uncompressed 8000x8000 PNG.","commonSituations":"Phone/procamera photos at full resolution; TIFF/BMP sources base64'd without re-encoding; a list of references where each passes a smaller per-item mental budget but one outlier dominates.","solutions":["Downscale and re-encode references to JPEG/WebP before base64 (see validationCode).","Target <= 2048px on the short edge — beyond that the reference pipeline rescales anyway.","Check len(b64) <= 32*1024*1024 per item before submitting batches."],"exampleFix":"# before\nb64 = base64.b64encode(open('raw_photo.png', 'rb').read()).decode()\n\n# after\nfrom PIL import Image\nimport io, base64\nimg = Image.open('raw_photo.png')\nimg.thumbnail((2048, 2048))\nbuf = io.BytesIO(); img.save(buf, 'JPEG', quality=90)\nb64 = base64.b64encode(buf.getvalue()).decode()","handlingStrategy":"validation","validationCode":"MAX_B64 = 32 * 1024 * 1024\ndef references_within_limit(refs: list[str] | None) -> bool:\n    return refs is None or all(len(r) <= MAX_B64 for r in refs)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Re-encode references to JPEG/WebP at <= 2048px short edge","Check len(base64) per item before batch submit","The limit is per-item, not per-request — count each reference separately"],"tags":["pydantic","validation","diffusion","payload-limit","base64","reference-images"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}