{"record":{"id":"fcc3ac3b7e5a5f6f","repo":"unslothai/unsloth","slug":"every-seed-must-be-between-0-and-2-53-1-json-s","errorCode":null,"errorMessage":"every seed must be between 0 and 2**53 - 1 (JSON-safe)","messagePattern":"every seed must be between 0 and 2\\*\\*53 - 1 \\(JSON-safe\\)","errorType":"validation","errorClass":"ValueError","httpStatus":400,"severity":"error","filePath":"studio/backend/core/inference/diffusion_batched.py","lineNumber":72,"sourceCode":"    - neither: ``batch_size`` images of ``prompt`` with derived seeds\n      base..base+batch_size-1 (each masked JSON-safe).\n\n    ``draw_seed`` supplies a fresh random base when the caller sent none (the\n    engine passes a ``torch.Generator`` draw). Raises ``ValueError`` on empty /\n    oversized lists, a length mismatch, or an out-of-range seed.\"\"\"\n    if prompts is not None:\n        if not prompts or not all(isinstance(p, str) and p.strip() for p in prompts):\n            raise ValueError(\"prompts must be a non-empty list of non-empty strings\")\n        if len(prompts) > MAX_BATCH_IMAGES:\n            raise ValueError(f\"prompts supports at most {MAX_BATCH_IMAGES} entries per call\")\n    if seeds is not None:\n        if not seeds:\n            raise ValueError(\"seeds must be a non-empty list of integers\")\n        if len(seeds) > MAX_BATCH_IMAGES:\n            raise ValueError(f\"seeds supports at most {MAX_BATCH_IMAGES} entries per call\")\n        seeds = [int(s) for s in seeds]\n        if any(s < 0 or s > SEED_MASK for s in seeds):\n            raise ValueError(\"every seed must be between 0 and 2**53 - 1 (JSON-safe)\")\n        if prompts is not None and len(seeds) != len(prompts):\n            raise ValueError(\n                f\"prompts and seeds must have the same length \"\n                f\"(got {len(prompts)} prompts, {len(seeds)} seeds)\"\n            )\n\n    if prompts is not None:\n        count = len(prompts)\n    elif seeds is not None:\n        count = len(seeds)\n    else:\n        count = max(1, int(batch_size))\n\n    if seeds is not None:\n        job_seeds = seeds\n        base_seed = seeds[0]\n    else:\n        base_seed = int(seed) if seed is not None else int(draw_seed()) & SEED_MASK","sourceCodeStart":54,"sourceCodeEnd":90,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/inference/diffusion_batched.py#L54-L90","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Mask your seeds to 53 bits: seed & ((1 << 53) - 1).","Replace sentinel values like -1 (random) with an omitted/null seed so the engine draws a fresh one.","Validate range client-side: 0 <= int(s) <= 2**53 - 1."],"exampleFix":"# before\nengine.generate(prompt=p, seeds=[secrets.randbits(64), -1])\n# after\nmask = (1 << 53) - 1\nengine.generate(prompt=p, seeds=[secrets.randbits(53) & mask])  # or omit seeds for random draw","handlingStrategy":"validation","validationCode":"SEED_MASK = (1 << 53) - 1\n\ndef json_safe_seed(s) -> int:\n    s = int(s)\n    if not (0 <= s <= SEED_MASK):\n        raise ValueError(f\"seed {s} out of range\")\n    return s\n\ndef valid_seeds(seeds) -> bool:\n    return seeds is None or all(0 <= int(s) <= SEED_MASK for s in seeds)","typeGuard":"def is_json_safe_seed(v) -> bool:\n    return isinstance(v, int) and not isinstance(v, bool) and 0 <= v <= 2**53 - 1","tryCatchPattern":"try:\n    out = engine.generate(prompt=p, seeds=seeds)\nexcept ValueError as e:\n    if \"between 0 and 2**53 - 1\" in str(e):\n        seeds = [int(s) & ((1 << 53) - 1) for s in seeds]  # explicit policy: mask to 53 bits\n        out = engine.generate(prompt=p, seeds=seeds)\n    else:\n        raise","preventionTips":["Generate seeds with at most 53 bits of randomness.","Translate -1 'random' sentinels to omitted/null before sending.","Validate range in the client to avoid a wasted round trip."],"tags":["diffusion","seeds","validation","json-safety"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}