unslothai/unsloth · error · ValueError

resolution must be a multiple of 8 and >= 64

Error message

resolution must be a multiple of 8 and >= 64

What it means

The validator rejected a training resolution below 64 or not divisible by 8. Diffusion VAEs downsample by a power of two, so an off-grid resolution changes latent geometry (cropping/padding) silently, and sub-64px images are too small for the patch/latent structure to be valid. The check runs in validation, before GPU memory is touched.

Source

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

        Also coerces values that arrive as strings/blanks through the Studio config path
        (``learning_rate`` is preserved as a string there; ``hf_token`` defaults to "")."""
        resolved_family = resolve_trainable_family(self.base_model, self.model_family)
        if self.train_steps < 1:
            raise ValueError("train_steps must be >= 1")
        if not 0 <= int(self.num_epochs) <= 1000:
            raise ValueError("num_epochs must be between 0 and 1000 (0 uses train_steps)")
        if self.train_batch_size < 1:
            raise ValueError("train_batch_size must be >= 1")
        if self.gradient_accumulation_steps < 1:
            raise ValueError("gradient_accumulation_steps must be >= 1")
        if self.lora_rank < 1:
            raise ValueError("lora_rank must be >= 1")
        if self.lora_alpha is not None and self.lora_alpha < 1:
            raise ValueError(
                "lora_alpha must be >= 1 (a zero/negative alpha scales the adapter to nothing)"
            )
        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:

View on GitHub (pinned to 203007d190)

Solutions

  1. Round the resolution to the nearest multiple of 8 that is >= 64 (e.g. 500 -> 504 or 512).
  2. Use standard buckets: 512, 768, 1024 for image training.
  3. If shrinking for VRAM, do not go below 64; reduce batch size or resolution tier instead.

Example fix

# before
config = TrainConfig(resolution=500)

# after
config = TrainConfig(resolution=512)
Defensive patterns

Strategy: validation

Validate before calling

def check_resolution(v) -> int:
    r = int(v)
    if r < 64 or r % 8 != 0:
        raise ValueError(f"resolution must be a multiple of 8 and >= 64, got {r}")
    return r

def snap_resolution(v) -> int:
    return max(64, (int(v) // 8) * 8)

Type guard

def is_valid_resolution(v) -> bool:
    try:
        r = int(v)
        return r >= 64 and r % 8 == 0
    except (TypeError, ValueError):
        return False

Try / catch

try:
    session.submit_training(config)
except ValueError as e:
    if "resolution" in str(e) and "multiple of 8" in str(e):
        config.resolution = snap_resolution(config.resolution)
        session.submit_training(config)
    else:
        raise

Prevention

When it happens

Trigger: A training request with resolution like 100, 500, 63, or 48 — anything < 64 or not a multiple of 8. Typically from free-form numeric fields, downscale experiments, or configs generated from arbitrary image dimensions.

Common situations: Matching resolution to a dataset's native size (e.g. 512x384 crops work, but 500 does not); low-VRAM users trying very small resolutions like 32; typo'd values.

Related errors

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