unslothai/unsloth · error · RuntimeError
MiniMax-H3 needs about {required_vram_gb:.1f} GB available V
Error message
MiniMax-H3 needs about {required_vram_gb:.1f} GB available VRAM for {width}x{height} at {frames} frames; {available_vram_gb:.1f} GB is available. Lower the resolution or duration, or load the GGUF artifact. What it means
Raised before running MiniMax-H3 in Diffusers when the estimated VRAM floor for the requested width/height/frames exceeds the currently available VRAM plus a 0.25 GB tolerance. The estimate is computed by estimate_h3_diffusers_vram_gb() using the resident sizes of the engaged text encoder and transformer (accounting for their quantization tier and whether the denoiser is pinned), so the floor tracks the checkpoint variant actually loaded. It is a preflight guard: the run would OOM mid-denoise otherwise.
Source
Thrown at studio/backend/core/inference/video.py:5044
else 0
)
available_vram_gb = (free_bytes + reserved_bytes) / 1_000_000_000
# Size the floor from the components this load ACTUALLY holds, not from
# the released bfloat16 pair. Both fields are the ENGAGED schemes (a
# declined or failed request is recorded as None at load), so a dense
# fallback keeps the dense floor.
required_vram_gb = estimate_h3_diffusers_vram_gb(
width,
height,
frames,
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),
transformer_pinned = bool(getattr(state, "h3_denoiser_pinned", False)),
)
if available_vram_gb + 0.25 < required_vram_gb:
raise RuntimeError(
f"MiniMax-H3 needs about {required_vram_gb:.1f} GB available "
f"VRAM for {width}x{height} at {frames} frames; "
f"{available_vram_gb:.1f} GB is available. Lower the resolution "
"or duration, or load the GGUF artifact."
)
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(View on GitHub (pinned to 203007d190)
Solutions
- Free or reduce competing VRAM: close other generation jobs/processes and retry so available_vram_gb rises above the estimate.
- Lower the requested resolution (width/height) and/or duration (frames) until the estimate fits — the message names the exact numbers to aim for.
- Load the GGUF artifact instead of the dense weights, as the message suggests — quantized components shrink the resident text-encoder/transformer terms feeding the estimate.
- Select a more aggressive text_encoder_quant / transformer_quant tier in the model load so the floor drops.
Example fix
// before result = engine.generate_video(prompt="...", width=1920, height=1080, frames=244) // raises RuntimeError: needs ~46.2 GB, 22.9 GB available // after result = engine.generate_video(prompt="...", width=1280, height=720, frames=129) # or load the GGUF checkpoint / a heavier quant tier before generating
Defensive patterns
Strategy: validation
Validate before calling
import torch
MINIMUM_SLACK_GB = 0.25
def vram_fits(width: int, height: int, frames: int) -> tuple[bool, float, float]:
"""Mirror the preflight: available + 0.25 GB must cover the estimate."""
free_b, _total = torch.cuda.mem_get_info() if torch.cuda.is_available() else (0, 0)
available_gb = free_b / 1e9
required_gb = estimate_h3_diffusers_vram_gb(
width, height, frames,
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),
transformer_pinned=bool(getattr(state, "h3_denoiser_pinned", False)),
)
return available_gb + MINIMUM_SLACK_GB >= required_gb, required_gb, available_gb
ok, required, available = vram_fits(1280, 720, 129)
if not ok:
raise HTTPException(400, f"needs ~{required:.1f} GB, {available:.1f} GB free; lower res/duration or use GGUF") Type guard
null
Try / catch
try:
result = engine.generate_video(...)
except RuntimeError as e:
if "GB available VRAM" in str(e):
# retry loop: halve resolution or frame count, or ask for GGUF artifact
downgrade_and_retry(e)
else:
raise Prevention
- Preflight free VRAM (torch.cuda.mem_get_info) against the estimator before submitting large requests.
- Default to the GGUF artifact on GPUs below ~24 GB for MiniMax-H3.
- Serialize generation jobs so concurrent pipelines don't eat each other's VRAM headroom.
- Expose the estimator in the UI to disable resolution/duration combos that cannot fit.
When it happens
Trigger: Calling the studio video-generation path with a MiniMax-H3 (Diffusers engine) family model loaded and requesting a resolution/duration combination whose estimate exceeds free VRAM. Typically large canvases (e.g. 1080p-class) or long frame counts on a GPU with little headroom, with bf16 or lightly quantized text encoder/transformer resident.
Common situations: Requesting HD or long clips on a 16-24 GB card with the bf16 artifact; other processes (another generation, a desktop compositor, a stale Python process) holding VRAM; running a quantized transformer but the full bf16 text encoder, which keeps the floor high; upgrading frame count without lowering resolution.
Related errors
- MiniMax-H3 needs about {required_host_gb:.0f} GB available s
- MiniMax-H3 needs the Diffusers revision bundled with this St
- Local base_repo is not a diffusers pipeline directory (no {i
- text_encoder_quant='{requested}' could not be used: {reason}
- The requested LoRA adapters could not be applied: baking ada
AI-assisted analysis of unslothai/unsloth@203007d190 (2026-08-15).
Data as JSON: /api/errors/1f3410e4b208567d.
Report an issue: GitHub.