{"record":{"id":"1f3410e4b208567d","repo":"unslothai/unsloth","slug":"minimax-h3-needs-about-required-vram-gb-1f-gb-a","errorCode":null,"errorMessage":"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.","messagePattern":"MiniMax-H3 needs about (.+?) GB available VRAM for (.+?)x(.+?) at (.+?) frames; (.+?) GB is available\\. Lower the resolution or duration, or load the GGUF artifact\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"studio/backend/core/inference/video.py","lineNumber":5044,"sourceCode":"                            else 0\n                        )\n                        available_vram_gb = (free_bytes + reserved_bytes) / 1_000_000_000\n                        # Size the floor from the components this load ACTUALLY holds, not from\n                        # the released bfloat16 pair. Both fields are the ENGAGED schemes (a\n                        # declined or failed request is recorded as None at load), so a dense\n                        # fallback keeps the dense floor.\n                        required_vram_gb = estimate_h3_diffusers_vram_gb(\n                            width,\n                            height,\n                            frames,\n                            text_encoder_gb = h3_te_resident_gb(\n                                state.text_encoder_quant, bf16_gb = H3_TEXT_ENCODER_BF16_GB\n                            ),\n                            transformer_gb = h3_transformer_resident_gb(state.transformer_quant),\n                            transformer_pinned = bool(getattr(state, \"h3_denoiser_pinned\", False)),\n                        )\n                        if available_vram_gb + 0.25 < required_vram_gb:\n                            raise RuntimeError(\n                                f\"MiniMax-H3 needs about {required_vram_gb:.1f} GB available \"\n                                f\"VRAM for {width}x{height} at {frames} frames; \"\n                                f\"{available_vram_gb:.1f} GB is available. Lower the resolution \"\n                                \"or duration, or load the GGUF artifact.\"\n                            )\n\n                        import psutil\n\n                        process_rss = psutil.Process().memory_info().rss\n                        host_capacity_gb = (\n                            psutil.virtual_memory().available + process_rss\n                        ) / 1_000_000_000\n                        # Same engaged components as the VRAM floor above. Sizing one from what\n                        # the load holds and the other from the released pair refuses exactly the\n                        # configuration the quantized components exist for.\n                        required_host_gb = estimate_h3_diffusers_host_ram_gb(\n                            available_vram_gb,\n                            text_encoder_gb = h3_te_resident_gb(","sourceCodeStart":5026,"sourceCodeEnd":5062,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/inference/video.py#L5026-L5062","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nresult = engine.generate_video(prompt=\"...\", width=1920, height=1080, frames=244)\n// raises RuntimeError: needs ~46.2 GB, 22.9 GB available\n\n// after\nresult = engine.generate_video(prompt=\"...\", width=1280, height=720, frames=129)\n# or load the GGUF checkpoint / a heavier quant tier before generating","handlingStrategy":"validation","validationCode":"import torch\n\nMINIMUM_SLACK_GB = 0.25\n\ndef vram_fits(width: int, height: int, frames: int) -> tuple[bool, float, float]:\n    \"\"\"Mirror the preflight: available + 0.25 GB must cover the estimate.\"\"\"\n    free_b, _total = torch.cuda.mem_get_info() if torch.cuda.is_available() else (0, 0)\n    available_gb = free_b / 1e9\n    required_gb = estimate_h3_diffusers_vram_gb(\n        width, height, frames,\n        text_encoder_gb=h3_te_resident_gb(state.text_encoder_quant, bf16_gb=H3_TEXT_ENCODER_BF16_GB),\n        transformer_gb=h3_transformer_resident_gb(state.transformer_quant),\n        transformer_pinned=bool(getattr(state, \"h3_denoiser_pinned\", False)),\n    )\n    return available_gb + MINIMUM_SLACK_GB >= required_gb, required_gb, available_gb\n\nok, required, available = vram_fits(1280, 720, 129)\nif not ok:\n    raise HTTPException(400, f\"needs ~{required:.1f} GB, {available:.1f} GB free; lower res/duration or use GGUF\")","typeGuard":"null","tryCatchPattern":"try:\n    result = engine.generate_video(...)\nexcept RuntimeError as e:\n    if \"GB available VRAM\" in str(e):\n        # retry loop: halve resolution or frame count, or ask for GGUF artifact\n        downgrade_and_retry(e)\n    else:\n        raise","preventionTips":["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."],"tags":["vram","minimax-h3","video-generation","preflight","diffusers"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}