unslothai/unsloth · error · ValueError

every seed must be between 0 and 2**53 - 1 (JSON-safe)

Error message

every seed must be between 0 and 2**53 - 1 (JSON-safe)

What it means

Every seed must lie in [0, 2**53 - 1] (SEED_MASK). The bound exists because seeds travel through JSON and must stay exactly representable as IEEE-754 doubles / JSON-safe integers; values outside the range are coerced with int() first, then rejected if negative or above the mask.

Source

Thrown at studio/backend/core/inference/diffusion_batched.py:72

    - neither: ``batch_size`` images of ``prompt`` with derived seeds
      base..base+batch_size-1 (each masked JSON-safe).

    ``draw_seed`` supplies a fresh random base when the caller sent none (the
    engine passes a ``torch.Generator`` draw). Raises ``ValueError`` on empty /
    oversized lists, a length mismatch, or an out-of-range seed."""
    if prompts is not None:
        if not prompts or not all(isinstance(p, str) and p.strip() for p in prompts):
            raise ValueError("prompts must be a non-empty list of non-empty strings")
        if len(prompts) > MAX_BATCH_IMAGES:
            raise ValueError(f"prompts supports at most {MAX_BATCH_IMAGES} entries per call")
    if seeds is not None:
        if not seeds:
            raise ValueError("seeds must be a non-empty list of integers")
        if len(seeds) > MAX_BATCH_IMAGES:
            raise ValueError(f"seeds supports at most {MAX_BATCH_IMAGES} entries per call")
        seeds = [int(s) for s in seeds]
        if any(s < 0 or s > SEED_MASK for s in seeds):
            raise ValueError("every seed must be between 0 and 2**53 - 1 (JSON-safe)")
        if prompts is not None and len(seeds) != len(prompts):
            raise ValueError(
                f"prompts and seeds must have the same length "
                f"(got {len(prompts)} prompts, {len(seeds)} seeds)"
            )

    if prompts is not None:
        count = len(prompts)
    elif seeds is not None:
        count = len(seeds)
    else:
        count = max(1, int(batch_size))

    if seeds is not None:
        job_seeds = seeds
        base_seed = seeds[0]
    else:
        base_seed = int(seed) if seed is not None else int(draw_seed()) & SEED_MASK

View on GitHub (pinned to 203007d190)

Solutions

  1. Mask your seeds to 53 bits: seed & ((1 << 53) - 1).
  2. Replace sentinel values like -1 (random) with an omitted/null seed so the engine draws a fresh one.
  3. Validate range client-side: 0 <= int(s) <= 2**53 - 1.

Example fix

# before
engine.generate(prompt=p, seeds=[secrets.randbits(64), -1])
# after
mask = (1 << 53) - 1
engine.generate(prompt=p, seeds=[secrets.randbits(53) & mask])  # or omit seeds for random draw
Defensive patterns

Strategy: validation

Validate before calling

SEED_MASK = (1 << 53) - 1

def json_safe_seed(s) -> int:
    s = int(s)
    if not (0 <= s <= SEED_MASK):
        raise ValueError(f"seed {s} out of range")
    return s

def valid_seeds(seeds) -> bool:
    return seeds is None or all(0 <= int(s) <= SEED_MASK for s in seeds)

Type guard

def is_json_safe_seed(v) -> bool:
    return isinstance(v, int) and not isinstance(v, bool) and 0 <= v <= 2**53 - 1

Try / catch

try:
    out = engine.generate(prompt=p, seeds=seeds)
except ValueError as e:
    if "between 0 and 2**53 - 1" in str(e):
        seeds = [int(s) & ((1 << 53) - 1) for s in seeds]  # explicit policy: mask to 53 bits
        out = engine.generate(prompt=p, seeds=seeds)
    else:
        raise

Prevention

When it happens

Trigger: Sending a negative seed (-1), or a seed above 9007199254740991 (e.g. a full 64-bit random uint64 from secrets.randbits(64)), or a float/bool that int() coerces out of range (True->1 is fine, 2**60 is not).

Common situations: Using numpy uint64 or os.urandom-derived 64-bit seeds; porting seeds from tools that allow the full 64-bit range; negative seeds common in other engines (e.g. some UIs use -1 for random) being passed through.

Related errors

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