{"record":{"id":"9c747bbad3cfc51b","repo":"unslothai/unsloth","slug":"seed-batch-size-1-must-not-exceed-2-53-1-so","errorCode":null,"errorMessage":"seed + batch_size - 1 must not exceed 2**53 - 1 so every per-image seed stays JSON-safe (lower the seed or the batch_size)","messagePattern":"seed \\+ batch_size - 1 must not exceed 2\\*\\*53 - 1 so every per-image seed stays JSON-safe \\(lower the seed or the batch_size\\)","errorType":"validation","errorClass":"ValueError","httpStatus":422,"severity":"error","filePath":"studio/backend/models/inference.py","lineNumber":3079,"sourceCode":"        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            )\n        return self\n\n\nclass GalleryImage(BaseModel):\n    \"\"\"A persisted image's full generation recipe (embedded in the PNG too).\"\"\"\n\n    id: str = Field(..., description = \"Stable id (the on-disk filename stem)\")\n    url: str = Field(..., description = \"Relative URL to fetch the PNG bytes\")\n    prompt: str = Field(..., description = \"Prompt used\")\n    negative_prompt: Optional[str] = Field(None, description = \"Negative prompt, if any\")\n    width: int = Field(..., description = \"Image width\")\n    height: int = Field(..., description = \"Image height\")\n    steps: int = Field(..., description = \"Denoising steps\")\n    guidance: float = Field(..., description = \"Guidance scale\")\n    seed: int = Field(..., description = \"Seed used for THIS image\")","sourceCodeStart":3061,"sourceCodeEnd":3097,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/models/inference.py#L3061-L3097","documentation":"Raised by a model_validator on DiffusionGenerateRequest when seed + batch_size - 1 exceeds 2**53-1. A batch derives per-image seeds as seed..seed+batch_size-1, so even an in-range seed can produce a derived top-of-batch seed that breaks JSON-safe integer round-tripping in the persisted gallery recipe.","triggerScenarios":"Sending seed near the maximum with a batch: e.g. {\"seed\": 9007199254740991, \"batch_size\": 4} — the third derived seed would exceed 2**53-1.","commonSituations":"Clients reusing a previously-returned maximal seed for a follow-up batch; UIs that expose the full 53-bit seed range plus a batch spinner; scripts that pin seeds at 2**53-1 for reproducibility then add batching.","solutions":["Lower the seed so seed + batch_size - 1 <= 2**53-1 (the message itself suggests this).","Or lower batch_size.","Clamp pinned seeds to 2**53-1 minus your max batch size at authoring time."],"exampleFix":"# before\npayload = {\"seed\": 2**53 - 1, \"batch_size\": 4}\n\n# after\nMAX_SEED = 2**53 - 1\nseed = min(seed, MAX_SEED - batch_size + 1)\npayload = {\"seed\": seed, \"batch_size\": batch_size}","handlingStrategy":"validation","validationCode":"MAX_SEED = 2 ** 53 - 1\ndef clamp_seed_for_batch(seed: int, batch_size: int) -> int:\n    return min(seed, MAX_SEED - batch_size + 1)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Clamp pinned seeds to 2**53-1 minus your max batch size","Remember batches derive seed..seed+batch_size-1 — headroom is required","Centralize the JSON-safe seed bound in one shared constant"],"tags":["pydantic","validation","diffusion","seeds","batch","json-safe-integers"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}