unslothai/unsloth · error · RuntimeError

MiniMax-H3 needs about {required_host_gb:.0f} GB available s

Error message

MiniMax-H3 needs about {required_host_gb:.0f} GB available system RAM at this VRAM tier; {host_capacity_gb:.1f} GB is available. Load the GGUF artifact instead.

What it means

Raised when the host-RAM floor for MiniMax-H3 in Diffusers exceeds what the machine can supply at the current VRAM tier. The required host RAM is derived from available VRAM (less VRAM means more components spill to CPU) using the same engaged component sizes as the VRAM check; capacity is psutil available memory plus this process's RSS, with a 0.5 GB tolerance. The comment explains the design: sizing one floor from what the load holds and the other from the released pair would refuse exactly the configuration quantized components exist for.

Source

Thrown at studio/backend/core/inference/video.py:5068

                        import psutil

                        process_rss = psutil.Process().memory_info().rss
                        host_capacity_gb = (
                            psutil.virtual_memory().available + process_rss
                        ) / 1_000_000_000
                        # Same engaged components as the VRAM floor above. Sizing one from what
                        # the load holds and the other from the released pair refuses exactly the
                        # configuration the quantized components exist for.
                        required_host_gb = estimate_h3_diffusers_host_ram_gb(
                            available_vram_gb,
                            text_encoder_gb = h3_te_resident_gb(
                                state.text_encoder_quant, bf16_gb = H3_TEXT_ENCODER_BF16_GB
                            ),
                            transformer_gb = h3_transformer_resident_gb(state.transformer_quant),
                        )
                        if host_capacity_gb + 0.5 < required_host_gb:
                            raise RuntimeError(
                                f"MiniMax-H3 needs about {required_host_gb:.0f} GB available "
                                f"system RAM at this VRAM tier; {host_capacity_gb:.1f} GB is "
                                "available. Load the GGUF artifact instead."
                            )

                # MPS seeds from the CPU generator too: diffusers reproduces a Metal seed only
                # that way, and the pipelines move the noise to the device themselves.
                generator_device = (
                    "cpu" if fam.modular_workflow or str(state.device) == "mps" else state.device
                )
                generator = torch.Generator(device = generator_device)
                if seed is None:
                    seed = int(generator.seed()) % (2**53)
                generator = generator.manual_seed(int(seed))

                # The RESOLVED request, snapshotted the moment it is known, so a failure logs what
                # actually ran rather than the caller's Nones. Without it the whole server-side
                # record of a failed video is the exception string: #8225 reported an OOM whose

View on GitHub (pinned to 203007d190)

Solutions

  1. Load the GGUF artifact as the message instructs — quantized resident sizes shrink both floors and the offload footprint.
  2. Free system RAM: stop other model-holding processes or restart the studio backend so psutil available rises.
  3. Move to a machine (or container) with more RAM for this tier.
  4. Reduce other resident models before generating (unload unused pipelines).

Example fix

// before: dense MiniMax-H3 on 12 GB GPU / 32 GB RAM host
engine.generate_video(prompt="...", width=1280, height=720, frames=129)
// raises: needs ~48 GB system RAM; 31.4 GB available

// after: load the GGUF artifact for the same model
engine.load_model("minimax-h3", artifact="gguf")
engine.generate_video(prompt="...", width=1280, height=720, frames=129)
Defensive patterns

Strategy: validation

Validate before calling

import psutil

HOST_SLACK_GB = 0.5

def host_ram_fits(available_vram_gb: float) -> tuple[bool, float, float]:
    rss = psutil.Process().memory_info().rss
    capacity_gb = (psutil.virtual_memory().available + rss) / 1e9
    required_gb = estimate_h3_diffusers_host_ram_gb(
        available_vram_gb,
        text_encoder_gb=h3_te_resident_gb(state.text_encoder_quant, bf16_gb=H3_TEXT_ENCODER_BF16_GB),
        transformer_gb=h3_transformer_resident_gb(state.transformer_quant),
    )
    return capacity_gb + HOST_SLACK_GB >= required_gb, required_gb, capacity_gb

ok, required, capacity = host_ram_fits(current_free_vram_gb)
if not ok:
    raise HTTPException(400, f"needs ~{required:.0f} GB system RAM, {capacity:.1f} GB available; load the GGUF artifact")

Type guard

null

Try / catch

try:
    result = engine.generate_video(...)
except RuntimeError as e:
    if "available system RAM" in str(e):
        switch_to_gguf_artifact()  # quantized components shrink both floors
    else:
        raise

Prevention

When it happens

Trigger: Calling MiniMax-H3 video generation in Diffusers on a machine where psutil.virtual_memory().available + process RSS is below estimate_h3_diffusers_host_ram_gb(available_vram_gb, ...) — typically a small-VRAM GPU forcing heavy CPU offload on a host with limited free RAM, with dense (bf16) components.

Common situations: Running the bf16 artifact on an 8-12 GB GPU with 32 GB RAM (offload pushes the floor past capacity); leaky long-lived server processes eating available RAM; containers with low memory limits; swapping headroom miscounted because capacity includes only this process's RSS.

Related errors

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