Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio video: refuse NaN / inf decodes for every family before a PIL / uint8 cast or clamp hides them (#15374)

Daniel Hanad79849da596
diff --git a/studio/backend/core/inference/video.py b/studio/backend/core/inference/video.py
index 8d0fa9d6c92..3896cd00353 100644
--- a/studio/backend/core/inference/video.py
+++ b/studio/backend/core/inference/video.py
@@ -281,6 +281,7 @@ from .video_families import (
from .video_frames import (
NON_FINITE_FRAMES_MSG,
NonFiniteFramesError,
+ finite_video_decode,
require_finite_frames,
uint8_video_frames,
)
@@ -12280,6 +12281,8 @@ class VideoBackend:
stack.enter_context(_denoise_phase(pipe, _enter_denoise))
# No video family has a denoise-to-decode callback, so the decoder itself reports the decode phase.
stack.enter_context(_decode_phase(pipe, _on_decode))
+ # NaN / inf pixels are refused at the decode, before a clamp or PIL / uint8 cast hides them.
+ stack.enter_context(finite_video_decode(pipe))
# The decoded clip becomes uint8 on the GPU, bit-identical to the np / pil export (video_frames).
stack.enter_context(uint8_video_frames(pipe))
if stream_session is not None:
diff --git a/studio/backend/core/inference/video_frames.py b/studio/backend/core/inference/video_frames.py
index 1a55e1c5cc2..2b44ba0fa8d 100644
--- a/studio/backend/core/inference/video_frames.py
+++ b/studio/backend/core/inference/video_frames.py
@@ -7,9 +7,14 @@
from __future__ import annotations
import contextlib
+import os
from typing import Any, Iterator, Optional
_SLICE_BYTES = 64 << 20
+# Elements per finiteness slice: the bool temporary stays at 16 MiB however long the clip.
+_FINITE_SLICE_ELEMS = 16 << 20
+# "0" turns off the in-render NaN / inf refusal (decode output and postprocess input); the encoder's check remains.
+NONFINITE_CHECK_ENV = "UNSLOTH_VIDEO_NONFINITE_CHECK"
def device_uint8(frames: Any) -> Optional[Any]:
@@ -70,14 +75,111 @@ def require_finite_frames(frames: Any) -> None:
import torch
except Exception: # noqa: BLE001
return
- if isinstance(frames, torch.Tensor) and frames.is_floating_point():
+ tensor = getattr(torch, "Tensor", None)
+ if tensor is not None and isinstance(frames, tensor) and frames.is_floating_point():
if not bool(torch.isfinite(frames).all()):
raise NonFiniteFramesError(NON_FINITE_FRAMES_MSG)
+def nonfinite_check_enabled() -> bool:
+ return os.environ.get(NONFINITE_CHECK_ENV, "").strip().lower() not in (
+ "0",
+ "false",
+ "no",
+ "off",
+ )
+
+
+def _tensor_all_finite(frames: Any) -> bool:
+ """Device-side finiteness of a float tensor, reduced in slices (no host copy, bounded temporary); one sync."""
+ import torch
+
+ if frames.numel() == 0:
+ return True
+ if frames.ndim == 0:
+ return bool(torch.isfinite(frames))
+ dim = 2 if frames.ndim == 5 else 0
+ count = frames.shape[dim]
+ step = max(1, _FINITE_SLICE_ELEMS // max(1, frames.numel() // max(1, count)))
+ ok = None
+ for start in range(0, count, step):
+ piece = torch.isfinite(frames.narrow(dim, start, min(step, count - start))).all()
+ ok = piece if ok is None else ok & piece
+ return bool(ok)
+
+
+def refuse_non_finite_tensor(frames: Any) -> None:
+ """Raise ``NonFiniteFramesError`` when ``frames`` is a float tensor holding NaN / inf; anything else passes."""
+ import torch
+
+ tensor = getattr(
+ torch, "Tensor", None
+ ) # a stubbed torch (tests) has no Tensor: nothing to check
+ if (
+ tensor is not None
+ and isinstance(frames, tensor)
+ and frames.is_floating_point()
+ and not _tensor_all_finite(frames)
+ ):
+ raise NonFiniteFramesError(NON_FINITE_FRAMES_MSG)
+
+
+def _decoded_frames(output: Any) -> Any:
+ """The pixel tensor of a ``vae.decode`` result: a tensor, ``(tensor, ...)`` or a ``DecoderOutput``."""
+ if isinstance(output, (tuple, list)):
+ return output[0] if output else None
+ sample = getattr(output, "sample", None)
+ return output if sample is None else sample
+
+
+FINITE_DECODE_LAYER = "video_finite_decode"
+
+
+def finite_video_decode(pipe: Any, attrs: "tuple[str, ...]" = ("vae",)) -> Iterator[None]:
+ """While active, a ``vae.decode`` whose pixels hold NaN / inf raises ``NonFiniteFramesError``: checked on the
+ device before any pipeline clamp (MiniMax-H3 clamps to [0, 1] first) or PIL / uint8 conversion hides it. The
+ output is returned untouched. A decode layer (decode_layers) over the load-time wrappers, so the fp16 decode's
+ fp32 rerun has run; it carries no below-scope marker, so the OOM scope stays intact (re-asserted after the wrap)."""
+ if not nonfinite_check_enabled():
+ yield
+ return
+ from . import decode_layers
+ from .diffusion_vae_oom import ensure_outermost
+
+ def make(inner: Any, _layer: Any) -> Any:
+ def decode(*args: Any, **kwargs: Any) -> Any:
+ output = inner(*args, **kwargs)
+ refuse_non_finite_tensor(_decoded_frames(output))
+ return output
+
+ return decode
+
+ layers: list = []
+ for name in attrs:
+ owner = getattr(pipe, name, None)
+ if owner is None or not callable(getattr(owner, "decode", None)):
+ continue
+ try:
+ layers.append(decode_layers.wrap(owner, "decode", FINITE_DECODE_LAYER, make))
+ except Exception: # noqa: BLE001 - a decoder that refuses the layer keeps the postprocess / encoder checks
+ continue
+ ensure_outermost(owner)
+ try:
+ yield
+ finally:
+ for layer in reversed(layers):
+ try:
+ decode_layers.unwrap(layer)
+ ensure_outermost(layer.owner)
+ except Exception: # noqa: BLE001
+ pass
+
+
@contextlib.contextmanager
def uint8_video_frames(pipe: Any) -> Iterator[None]:
- """While active, ``pipe.video_processor``'s np / pil ``postprocess_video`` returns CPU uint8 (B, F, H, W, C)."""
+ """While active, ``pipe.video_processor``'s np / pil ``postprocess_video`` returns CPU uint8 (B, F, H, W, C), and
+ refuses a float clip holding NaN / inf (any output type) with ``NonFiniteFramesError``."""
proc = getattr(pipe, "video_processor", None)
original = getattr(proc, "postprocess_video", None)
postprocess = getattr(proc, "postprocess", None)
@@ -87,12 +189,16 @@ def uint8_video_frames(pipe: Any) -> Iterator[None]:
import torch
had_own = "postprocess_video" in vars(proc)
+ check = nonfinite_check_enabled()
def postprocess_video(
video: Any,
output_type: str = "np",
**kwargs: Any,
) -> Any:
+ if check:
+ # Before the denormalize clamp (+inf -> 255) and the PIL cast (NaN -> 0) can hide a non-finite decode.
+ refuse_non_finite_tensor(video)
if (
output_type not in ("np", "pil")
or not isinstance(video, torch.Tensor)
diff --git a/studio/backend/tests/test_video_frames.py b/studio/backend/tests/test_video_frames.py
index 7ddabb05ac3..e1de5e06c11 100644
--- a/studio/backend/tests/test_video_frames.py
+++ b/studio/backend/tests/test_video_frames.py
@@ -91,7 +91,9 @@ def test_every_float32_near_a_rounding_boundary():
@pytest.mark.parametrize("bad", [float("nan"), 1.5, -0.25])
@pytest.mark.parametrize("output_type", ["np", "pil"])
-def test_out_of_range_takes_the_original_postprocess(bad, output_type):
+def test_out_of_range_takes_the_original_postprocess(bad, output_type, monkeypatch):
+ # NaN is refused by default (test_video_nonfinite_every_family); with the check off it keeps the original path.
+ monkeypatch.setenv("UNSLOTH_VIDEO_NONFINITE_CHECK", "0")
vp = VideoProcessor(vae_scale_factor = 8, do_normalize = False)
video = _clip(torch.float32, normalized = False)
video[0, 0, 1, 2, 3] = bad
diff --git a/studio/backend/tests/test_video_nonfinite_every_family.py b/studio/backend/tests/test_video_nonfinite_every_family.py
new file mode 100644
index 00000000000..92f11c1e044
--- /dev/null
+++ b/studio/backend/tests/test_video_nonfinite_every_family.py
@@ -0,0 +1,228 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Every video family refuses a NaN / inf decode with NonFiniteFramesError, before a PIL / uint8 cast or a clamp hides
+it; a finite clip is untouched."""
+
+import contextlib
+import types
+from pathlib import Path
+
+import numpy as np
+import pytest
+
+torch = pytest.importorskip("torch")
+pytest.importorskip("diffusers")
+from diffusers.models.autoencoders.vae import DecoderOutput # noqa: E402
+from diffusers.video_processor import VideoProcessor # noqa: E402
+
+from core.inference import video_frames as VF # noqa: E402
+from core.inference.video_frames import ( # noqa: E402
+ NON_FINITE_FRAMES_MSG,
+ NonFiniteFramesError,
+ uint8_video_frames,
+)
+
+# Absent before this change: a null context, so the tests fail on behaviour rather than on import.
+_finite_video_decode = getattr(VF, "finite_video_decode", lambda pipe: contextlib.nullcontext())
+_ENV = "UNSLOTH_VIDEO_NONFINITE_CHECK"
+
+
+class _VAE(torch.nn.Module):
+ def __init__(
+ self,
+ pixels,
+ style = "tuple",
+ ):
+ super().__init__()
+ self.pixels = pixels
+ self.style = style
+
+ def decode(
+ self,
+ z,
+ *args,
+ return_dict = True,
+ **kwargs,
+ ):
+ if self.style == "output": # Cosmos3: self.vae.decode(z).sample
+ return DecoderOutput(sample = self.pixels)
+ return (self.pixels,)
+
+
+def _pixels(
+ bad = None,
+ frames = 4,
+ where = (0, 0, 1, 2, 3),
+):
+ g = torch.Generator().manual_seed(0)
+ video = torch.rand((1, 3, frames, 16, 24), generator = g) * 2 - 1
+ if bad is not None:
+ video[where] = bad
+ return video
+
+
+def _render(pipe, family):
+ if family == "wan": # WanPipeline / HunyuanVideo15Pipeline: output_type="np"
+ return pipe.video_processor.postprocess_video(
+ pipe.vae.decode(None, return_dict = False)[0], output_type = "np"
+ )
+ if family == "ltx2": # LTX2Pipeline (LTX-2, LTX-2.3, LTX-2.5 stage 2): output_type="pil"
+ return pipe.video_processor.postprocess_video(
+ pipe.vae.decode(None, None, return_dict = False)[0], output_type = "pil"
+ )
+ if family == "cosmos3": # Cosmos3OmniPipeline: output_type="pil"
+ decoded = pipe.vae.decode(None).sample
+ return pipe.video_processor.postprocess_video(decoded, output_type = "pil")[0]
+ if (
+ family == "h3"
+ ): # MiniMaxH3 modular decode step: denormalise + clamp(0, 1) BEFORE postprocess_video
+ video = pipe.vae.decode(None, return_dict = False)[0]
+ video = (video.float() * 0.5 + 0.5).clamp(0, 1)
+ return pipe.video_processor.postprocess_video(video, output_type = "pil")
+ raise AssertionError(family)
+
+
+def _pipe(pixels, family):
+ style = "output" if family == "cosmos3" else "tuple"
+ vp = VideoProcessor(vae_scale_factor = 8, do_normalize = family != "h3")
+ return types.SimpleNamespace(vae = _VAE(pixels, style), video_processor = vp)
+
+
+def _run(pipe, family):
+ with _finite_video_decode(pipe), uint8_video_frames(pipe):
+ return _render(pipe, family)
+
+
+FAMILIES = ["wan", "ltx2", "cosmos3", "h3"]
+
+
[email protected]("family", FAMILIES)
[email protected]("bad", [float("nan"), float("inf"), float("-inf")])
+def test_every_family_refuses_a_non_finite_decode(family, bad):
+ pipe = _pipe(_pixels(bad), family)
+ with pytest.raises(NonFiniteFramesError) as info:
+ _run(pipe, family)
+ assert str(info.value) == NON_FINITE_FRAMES_MSG
+
+
[email protected]("output_type", ["pil", "np"])
[email protected]("bad", [float("nan"), float("inf")])
+def test_postprocess_refuses_before_the_cast(output_type, bad):
+ # PIL: NaN became uint8 0 (a black pixel); np: +inf was clamped to 255. Both used to pass silently.
+ vp = VideoProcessor(vae_scale_factor = 8)
+ with uint8_video_frames(types.SimpleNamespace(video_processor = vp)):
+ with pytest.raises(NonFiniteFramesError):
+ vp.postprocess_video(_pixels(bad), output_type = output_type)
+ assert "postprocess_video" not in vars(vp)
+
+
+def test_a_late_frame_in_a_sliced_check_is_seen(monkeypatch):
+ monkeypatch.setattr(VF, "_FINITE_SLICE_ELEMS", 16 * 24 * 3, raising = False)
+ pipe = _pipe(_pixels(float("inf"), frames = 9, where = (0, 2, 8, 15, 23)), "ltx2")
+ with pytest.raises(NonFiniteFramesError):
+ _run(pipe, "ltx2")
+
+
[email protected]("family", FAMILIES)
+def test_a_finite_clip_is_bit_identical(family, monkeypatch):
+ pixels = _pixels()
+ got = _run(_pipe(pixels, family), family)
+ monkeypatch.setenv(_ENV, "0")
+ expected = _run(_pipe(pixels.clone(), family), family)
+ if family == "wan":
+ assert (
+ isinstance(got, torch.Tensor)
+ and got.dtype == torch.uint8
+ and torch.equal(got, expected)
+ )
+ return
+ exp = expected[0] if family != "cosmos3" else expected
+ out = got[0] if family != "cosmos3" else got
+ assert len(out) == len(exp) == pixels.shape[2]
+ assert all(np.array_equal(np.asarray(a), np.asarray(b)) for a, b in zip(out, exp))
+
+
+def test_decode_output_is_returned_untouched_and_the_slot_restored():
+ pixels = _pixels()
+ vae = _VAE(pixels)
+ pipe = types.SimpleNamespace(vae = vae)
+ assert "decode" not in vars(vae)
+ with _finite_video_decode(pipe):
+ assert "decode" in vars(vae)
+ assert vae.decode.__wrapped__ is not None
+ assert vae.decode(None)[0] is pixels
+ assert "decode" not in vars(vae)
+
+
+def test_an_own_decode_is_put_back():
+ vae = _VAE(_pixels())
+ own = vae.decode
+ vae.decode = own
+ with _finite_video_decode(types.SimpleNamespace(vae = vae)):
+ assert vars(vae)["decode"] is not own
+ assert vars(vae)["decode"] is own
+
+
[email protected]("family", FAMILIES)
+def test_kill_switch_restores_the_previous_behaviour(family, monkeypatch):
+ monkeypatch.setenv(_ENV, "0")
+ pipe = _pipe(_pixels(float("inf")), family)
+ vae = pipe.vae
+ with _finite_video_decode(pipe):
+ assert "decode" not in vars(vae)
+ _run(pipe, family)
+
+
+def test_the_render_stack_enters_the_decode_check():
+ source = (Path(VF.__file__).with_name("video.py")).read_text(encoding = "utf-8")
+ assert "stack.enter_context(finite_video_decode(pipe))" in source
+
+
+class _ScopedVAE(torch.nn.Module):
+ """A VAE whose public decode calls ``_decode`` (stock diffusers shape), so the OOM ladder and scope install."""
+
+ def __init__(self, pixels):
+ super().__init__()
+ self.pixels = pixels
+ self.use_tiling = False
+
+ def enable_tiling(self):
+ self.use_tiling = True
+
+ def _decode(
+ self,
+ z,
+ return_dict = True,
+ ):
+ return (self.pixels,)
+
+ def decode(
+ self,
+ z,
+ return_dict = True,
+ ):
+ return self._decode(z, return_dict = return_dict)
+
+
[email protected]("bad", [None, float("nan")])
+def test_the_oom_scope_stays_intact_and_is_put_back(bad):
+ from core.inference import decode_layers
+ from core.inference import diffusion_vae_oom as O
+
+ pixels = _pixels(bad)
+ vae = _ScopedVAE(pixels)
+ assert O.install(vae)
+ scope = vars(vae)["decode"]
+ assert O._scope_intact(vae)
+ with _finite_video_decode(types.SimpleNamespace(vae = vae)):
+ assert vars(vae)["decode"] is not scope
+ assert O._scope_intact(vae) # the finiteness layer sits over the scope without breaking it
+ assert decode_layers.find(vae, "decode", "video_finite_decode") is not None
+ if bad is None:
+ assert vae.decode(None)[0] is pixels
+ else:
+ with pytest.raises(NonFiniteFramesError):
+ vae.decode(None)
+ assert vars(vae)["decode"] is scope and O._scope_intact(vae)
+ assert decode_layers.find(vae, "decode", "video_finite_decode") is None