MiniMax H3 • VRAM Pressure Guard (internal)

Here's a failure mode you know if you've run long video: the sampling starts fine, VRAM looks healthy, and then twenty minutes in, mid-sequence, the whole thing dies with a CUDA OOM. The reason is that free VRAM before the transformer workspaces get allocated is not the same as free VRAM after. MiniMaxH3LatentLabVRAMPressureGuard is the pack's answer: a SAMPLER wrapper that watches VRAM during sampling and flushes the cache before pressure turns into a crash.

You feed it a sampler (SAMPLER) plus three thresholds, and it hands back the wrapped sampler plus a guard_state (the pack's H3_VRAM_GUARD_STATE diagnostic object).

• free_threshold_mb (default 768) - if free VRAM drops below this during sampling, the guard triggers.
• cache_threshold_mb (default 4096) - if the reserved CUDA cache grows above this, it triggers too.
• max_flushes (default 2) - how many times the guard is allowed to flush per run. The cap matters: a cache flush costs time, and flushing in a loop helps nobody.

How it behaves

The wrapper wraps the sampler and, at checkpoints through the run, looks at torch.cuda memory stats. When either threshold trips, it soft-empties the CUDA cache to reclaim reserved-but-unused blocks, counts the flush, and keeps going - up to max_flushes. Every check and flush is recorded in guard_state (checks, flushes, events), so you can see what it actually did. Feed that state into the pack's VRAM Cache Cleanup node at the end and it gets folded into the final report.

The defaults are sensible for a 16 GB card running H3: 768 MB of free headroom is a reasonable canary, 4 GB of reserved cache is a reasonable ceiling, and 2 flushes is a conservative budget. For tighter cards, dropping free_threshold_mb to 512 and keeping the flush cap low is the standard move - you want the guard to catch real pressure, not thrash constantly.

Should you use it?

It's an "(internal)" node, and the pack's public Sampler handles this automatically under memory_mode = auto. You'll typically meet this node inside a saved workflow, or when you're hand-building a sampler chain and want the safety net. The honest use for a beginner is telemetry: wire guard_state somewhere visible and watch whether a run is living on its flushes - if it hits max_flushes every time, your segments are too long for the card and you should shorten segment_duration instead of tuning thresholds.

Install

One pack, no extra deps:

cd ComfyUI/custom_nodes
git clone https://github.com/vizart-vj/ComfyUI-MiniMax-H3-LongMedia

Restart ComfyUI, or ComfyUI Manager → "MiniMax H3 LongMedia".

Gotchas

• If the guard is firing at its max flush budget constantly, the fix is smaller segments, not a bigger max_flushes. Throwing more flushes at a fundamentally oversized sequence just makes the run slower.
• Keep ComfyUI Dynamic VRAM enabled; the whole memory strategy leans on it.
• The H3 weights are license-excluded from the US, EU, UK and South Korea - pack-wide reminder.

It's the difference between discovering a run is too big at the 30-second mark and discovering it at the 20-minute mark. Not glamorous, but you'll be glad it's there.