unslothai/unsloth · error · ValueError

seed + batch_size - 1 must not exceed 2**53 - 1 so every per

Error message

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)

What it means

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.

Source

Thrown at studio/backend/models/inference.py:3079

        if value is not None:
            for item in value:
                if len(item) > 32 * 1024 * 1024:
                    raise ValueError("each reference image must be at most 32 MiB (base64)")
        return value

    @field_validator("width", "height")
    @classmethod
    def _multiple_of_16(cls, value: int) -> int:
        # Z-Image requires dimensions divisible by 16 (8x VAE downsample + 2x patch); non-multiples crash deep in the pipeline.
        if value % 16 != 0:
            raise ValueError("must be a multiple of 16")
        return value

    @model_validator(mode = "after")
    def _batch_seeds_json_safe(self) -> "DiffusionGenerateRequest":
        # 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.
        if self.seed is not None and self.seed + self.batch_size - 1 > 2**53 - 1:
            raise ValueError(
                "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)"
            )
        return self


class GalleryImage(BaseModel):
    """A persisted image's full generation recipe (embedded in the PNG too)."""

    id: str = Field(..., description = "Stable id (the on-disk filename stem)")
    url: str = Field(..., description = "Relative URL to fetch the PNG bytes")
    prompt: str = Field(..., description = "Prompt used")
    negative_prompt: Optional[str] = Field(None, description = "Negative prompt, if any")
    width: int = Field(..., description = "Image width")
    height: int = Field(..., description = "Image height")
    steps: int = Field(..., description = "Denoising steps")
    guidance: float = Field(..., description = "Guidance scale")
    seed: int = Field(..., description = "Seed used for THIS image")

View on GitHub (pinned to 203007d190)

Solutions

1. Lower the seed so seed + batch_size - 1 <= 2**53-1 (the message itself suggests this).
2. Or lower batch_size.
3. Clamp pinned seeds to 2**53-1 minus your max batch size at authoring time.

Example fix

# before
payload = {"seed": 2**53 - 1, "batch_size": 4}

# after
MAX_SEED = 2**53 - 1
seed = min(seed, MAX_SEED - batch_size + 1)
payload = {"seed": seed, "batch_size": batch_size}

MAX_SEED = 2 ** 53 - 1
def clamp_seed_for_batch(seed: int, batch_size: int) -> int:
    return min(seed, MAX_SEED - batch_size + 1)

When it happens

Trigger: Sending seed near the maximum with a batch: e.g. {"seed": 9007199254740991, "batch_size": 4} — the third derived seed would exceed 2**53-1.

Common situations: 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.

Related errors

• every seed must be between 0 and 2**53 - 1
• prompts and seeds must have the same length (got {len(self.p
• every prompt in prompts must be non-empty
• seeds must be a non-empty list of integers
• seeds supports at most {MAX_BATCH_IMAGES} entries per call

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