unslothai/unsloth · error · ValueError

seed must fit in torch's 64-bit range

Error message

seed must fit in torch's 64-bit range

What it means

The validator rejected a seed outside the range torch can accept. torch.manual_seed unpacks its argument as int64/uint64, so anything wider raises inside the trainer — after resident GPU models have already been evicted, wasting time. This check fails fast during validation instead.

Source

Thrown at studio/backend/core/training/diffusion_train_common.py:1038

            )
        if self.resolution < 64 or self.resolution % 8 != 0:
            raise ValueError("resolution must be a multiple of 8 and >= 64")
        # A video family's VAE compresses space by 32, so an off-grid resolution changes the
        # latent geometry silently. Refuse it here, before the GPU models are evicted.
        if (
            resolved_family in TRAINABLE_VIDEO_FAMILIES
            and self.resolution % _VIDEO_RESOLUTION_MULTIPLE != 0
        ):
            raise ValueError(
                f"'{resolved_family}' trains at a resolution that is a multiple of "
                f"{_VIDEO_RESOLUTION_MULTIPLE} (its VAE compresses space by that factor); "
                f"got {self.resolution}."
            )
        if self.mixed_precision not in ("bf16", "fp16", "no"):
            raise ValueError("mixed_precision must be one of bf16 / fp16 / no")
        # torch.manual_seed unpacks int64/uint64, so anything wider raises inside the trainer, after eviction. Catch it here.
        if not -(2**63) <= int(self.seed) <= 2**64 - 1:
            raise ValueError("seed must fit in torch's 64-bit range")
        # Refuse fp16 for a bf16-only DiT family up front, before evicting resident models.
        if self.mixed_precision == "fp16" and resolved_family in _FORCE_BF16_FAMILIES:
            raise ValueError(
                f"'{resolved_family}' LoRA training requires bf16: fp16 overflows its fp32 "
                f"RoPE / embedder internals. Set mixed precision to bf16."
            )
        if str(self.lr_scheduler) not in _LR_SCHEDULERS:
            raise ValueError(
                f"lr_scheduler must be one of {', '.join(sorted(_LR_SCHEDULERS))}; "
                f"got {self.lr_scheduler!r}"
            )
        if not 1 <= int(self.cache_variants) <= 16:
            raise ValueError("cache_variants must be between 1 and 16")
        # Checkpointing knobs. Rejected here, before the route evicts resident GPU models, rather than deep in the loop.
        try:
            save_steps = int(self.save_steps or 0)
            save_total_limit = int(self.save_total_limit or 0)
        except (TypeError, ValueError) as exc:

View on GitHub (pinned to 203007d190)

Solutions

1. Clamp the seed to [-(2**63), 2**64 - 1]; for practical purposes use 0 <= seed < 2**63 - 1.
2. When deriving from a hash, truncate: seed = int.from_bytes(h.digest()[:8], 'big').
3. Prefer plain small integers from random.randrange(2**63 - 1).

Example fix

# before
seed = int.from_bytes(uuid.uuid4().bytes, 'big')  # 128-bit, too wide

# after
seed = int.from_bytes(uuid.uuid4().bytes[:8], 'big')  # 64-bit

SEED_MIN, SEED_MAX = -(2**63), 2**64 - 1

def check_seed(v) -> int:
    s = int(v)
    if not SEED_MIN <= s <= SEED_MAX:
        raise ValueError(f"seed must fit [{SEED_MIN}, {SEED_MAX}], got {s}")
    return s

def clamp_seed(v) -> int:
    return max(0, min(int(v), 2**63 - 1))

def is_valid_seed(v) -> bool:
    try:
        return -(2**63) <= int(v) <= 2**64 - 1
    except (TypeError, ValueError):
        return False

try:
    session.submit_training(config)
except ValueError as e:
    if "seed" in str(e):
        config.seed = config.seed % (2**63)  # fold into range and retry
        session.submit_training(config)
    else:
        raise

When it happens

Trigger: Passing seed = 2**64 (or larger), a negative value below -(2**63), or a string that parses to such a number. Typical sources: generating seeds from 128-bit UUIDs/hashes, numpy seeds cast incorrectly, or randomness sources that produce arbitrarily large Python ints.

Common situations: seed = int.from_bytes(uuid4().bytes, 'big'); seed derived from a hash (blake2/sha) truncated to 128 bits; porting seeds from libraries that allow arbitrary ints (Python's random accepts any non-negative int).

Related errors

• gradient_accumulation_steps must be >= 1
• lora_rank must be >= 1
• lora_alpha must be >= 1 (a zero/negative alpha scales the ad
• resolution must be a multiple of 8 and >= 64
• mixed_precision must be one of bf16 / fp16 / no

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