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.

Catch a temporary patch that stops applying instead of only logging it (#11198)

Daniel Hane00e8bb7fd90
diff --git a/tests/test_import_time_floors.py b/tests/test_import_time_floors.py
index 677c51543f8..af411e7e8a7 100644
--- a/tests/test_import_time_floors.py
+++ b/tests/test_import_time_floors.py
@@ -790,8 +790,12 @@ class _CollectingLogger:
self.warnings.append(message)
-def _isolated_run_temporary_patches(patches, logger):
- """`_run_temporary_patches` alone, with its two module globals supplied.
+def _isolated_run_temporary_patches(
+ patches,
+ logger,
+ outcomes = None,
+):
+ """`_run_temporary_patches` alone, with its module globals supplied.
Loading it out of the file rather than importing unsloth.models._utils keeps
this a test of the control flow and not of a full model-stack import.
@@ -806,7 +810,11 @@ def _isolated_run_temporary_patches(patches, logger):
else:
raise AssertionError("_run_temporary_patches is gone from unsloth/models/_utils.py")
- namespace = {"TEMPORARY_PATCHES": patches, "logger": logger}
+ namespace = {
+ "TEMPORARY_PATCHES": patches,
+ "logger": logger,
+ "TEMPORARY_PATCH_OUTCOMES": {} if outcomes is None else outcomes,
+ }
exec(compile(segment, str(path), "exec"), namespace)
return namespace["_run_temporary_patches"]
diff --git a/tests/test_temporary_patch_coverage.py b/tests/test_temporary_patch_coverage.py
new file mode 100644
index 00000000000..2863b35c30b
--- /dev/null
+++ b/tests/test_temporary_patch_coverage.py
@@ -0,0 +1,430 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2023-present Daniel Han-Chen & the Unsloth team. All rights reserved.
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+"""A temporary patch that stops applying has to be caught, not just logged.
+
+`_run_temporary_patches` calls each entry of `TEMPORARY_PATCHES` inside
+`except Exception` and emits `logger.warning`, so `import unsloth` survives a
+patch that blows up (#3130 ended the import outright on a `SyntaxError` from
+one). The cost of that is a silent one: a patch can rot away against a new
+transformers and every job stays green, because the only trace is a warning
+line nobody asserts on.
+
+The gate here reads the outcome that `_run_temporary_patches` now records and
+fails on any patch that RAISED.
+
+Why not assert a list of patch names, or a count. Which patches apply depends
+entirely on what is installed. `patch_gemma4_moe` has nothing to attach itself
+to on transformers 4.57.6 and returns without doing anything; the MoE
+quantization patches check `is_transformers_v5_moe_quantization_available()`
+first and decline on v4. A name list or a count would go red on the 4.57.6 leg
+of the matrix for patches that are behaving exactly as designed, and would need
+editing every time a patch is added. So the question asked is not "did patch X
+apply" but "did any patch raise", which is version independent: declining
+cleanly is a normal return, raising never is.
+"""
+
+import ast
+import gc
+import json
+import os
+import pathlib
+import subprocess
+import sys
+import weakref
+
+import pytest
+
+_ROOT = pathlib.Path(__file__).resolve().parents[1]
+_UTILS = _ROOT / "unsloth" / "models" / "_utils.py"
+
+_BEGIN = "UNSLOTH_PATCH_REPORT_BEGIN"
+_END = "UNSLOTH_PATCH_REPORT_END"
+
+# Imports unsloth for real, then dumps what `_run_temporary_patches` recorded.
+# The injection point is where a mutation control installs an extra patch and
+# re-runs the pass, so the control travels the same code path as the gate.
+_CHILD = """
+import json
+import unsloth # noqa: F401
+import unsloth.models._utils as _utils
+
+# `import unsloth` only runs the "init" pass. The other two run from
+# unsloth_compile_transformers around the compiler, and a phase-aware patch
+# branches on which one it is (patch_Gemma4_static_cache_backport and
+# patch_gpt_oss_for_grpo both return immediately unless phase == post_compile),
+# so a patch can be perfectly quiet at import and raise only in a compile pass.
+# Running the two passes here executes those branches without standing up a
+# model or a compiler. It is not the full production state -- post_compile
+# normally runs after _unsloth_compile_transformers has swapped classes -- so
+# this catches a patch that raises on its own terms, not one that only raises
+# against a compiled model.
+_utils._run_temporary_patches("pre_compile")
+_utils._run_temporary_patches("post_compile")
+
+{injection}
+
+report = {{}}
+for phase, outcome in _utils.TEMPORARY_PATCH_OUTCOMES.items():
+ report[phase] = {{
+ "completed": [getattr(p, "__name__", repr(p)) for p in outcome["completed"]],
+ "raised": [
+ [getattr(p, "__name__", repr(p)), type(e).__name__, str(e)]
+ for p, e in outcome["raised"]
+ ],
+ }}
+print({begin!r})
+print(json.dumps(report))
+print({end!r})
+"""
+
+_NO_ACCELERATOR = (
+ "Unsloth cannot find any torch accelerator",
+ "No CUDA GPUs are available",
+ "Torch not compiled with CUDA enabled",
+)
+
+
+def _spawn(code, **extra_env):
+ path = [str(_ROOT)]
+ if os.environ.get("PYTHONPATH"):
+ path.append(os.environ["PYTHONPATH"])
+ return subprocess.run(
+ [sys.executable, "-c", code],
+ capture_output = True,
+ text = True,
+ env = dict(os.environ, PYTHONPATH = os.pathsep.join(path), **extra_env),
+ timeout = 1800,
+ )
+
+
+def _collect(injection = ""):
+ """The real import, in a fresh interpreter, reported as plain data.
+
+ A host with no accelerator at all cannot finish `import unsloth` without
+ `UNSLOTH_ALLOW_CPU=1`, and CI's CPU job is exactly that. Retrying on that
+ one symptom rather than probing the host keeps this free of any assumption
+ about which accelerator (or operating system) is present.
+ """
+ code = _CHILD.format(injection = injection, begin = _BEGIN, end = _END)
+ result = _spawn(code)
+ if result.returncode != 0 and any(m in result.stderr for m in _NO_ACCELERATOR):
+ result = _spawn(code, UNSLOTH_ALLOW_CPU = "1")
+ if result.returncode != 0 or _BEGIN not in result.stdout:
+ raise AssertionError(
+ "could not import unsloth to read the temporary patch outcomes\n"
+ f"exit {result.returncode}\n--- stdout ---\n{result.stdout}\n"
+ f"--- stderr ---\n{result.stderr}"
+ )
+ body = result.stdout.split(_BEGIN, 1)[1].split(_END, 1)[0]
+ return json.loads(body)
+
+
+def _assert_no_patch_raised(report):
+ """The gate. Fails naming every patch that raised, and with what."""
+ failures = []
+ for phase in sorted(report):
+ for name, exception_type, message in report[phase]["raised"]:
+ failures.append(f" {name} (phase {phase}): {exception_type}: {message}")
+ assert not failures, (
+ "PATCH COVERAGE LOST: these temporary patches raised and were swallowed by the "
+ "fail-soft handler in _run_temporary_patches, so they are no longer applied. A "
+ "patch that no longer has anything to patch on this library version must return "
+ "cleanly, not raise.\n" + "\n".join(failures)
+ )
+
+
[email protected](scope = "module")
+def _clean_report():
+ return _collect()
+
+
+# ------------------------------------------------------------------ the gate
+
+
+_PHASES = ("init", "pre_compile", "post_compile")
+
+
+def test_no_temporary_patch_raised_on_this_library_version(_clean_report):
+ assert _clean_report, "no phase was recorded at all, the bookkeeping is not running"
+ missing = [phase for phase in _PHASES if phase not in _clean_report]
+ assert not missing, f"no outcome was recorded for {missing}"
+ _assert_no_patch_raised(_clean_report)
+
+
[email protected]("phase", _PHASES)
+def test_every_pass_actually_ran_some_patches(_clean_report, phase):
+ # Guards the degenerate green: an empty TEMPORARY_PATCHES, or a pass that
+ # was never driven, would satisfy the gate above without applying anything.
+ # No upper or exact bound, and no names, so adding or removing a patch never
+ # touches this file.
+ assert _clean_report[phase][
+ "completed"
+ ], f"no temporary patch completed in the {phase} pass, so the gate above is vacuous there"
+
+
+# ------------------------------------------------- mutation controls
+# The gate is only worth having if it is sensitive to a patch that breaks and
+# insensitive to one that declines because this library version has nothing for
+# it to patch. Both controls go through the real import and the real recording.
+
+
+_RAISES = """
+def _mutation_control_patch_that_raises():
+ # What patch_merge_quantization_configs did in #3130: a SyntaxError out of
+ # an exec'd string, from inside a patch body.
+ raise SyntaxError("mutation control: this patch is broken")
+
+_utils.TEMPORARY_PATCHES.append(_mutation_control_patch_that_raises)
+_utils._run_temporary_patches("init")
+"""
+
+_DECLINES = """
+def _mutation_control_patch_that_declines(phase):
+ # The shape of every version-conditional patch in unsloth_zoo: look for the
+ # thing to patch, and return without touching anything when this library
+ # version does not have it.
+ try:
+ import a_module_no_transformers_release_ships # noqa: F401
+ except ImportError:
+ return
+ raise AssertionError("unreachable")
+
+_utils.TEMPORARY_PATCHES.append(_mutation_control_patch_that_declines)
+_utils._run_temporary_patches("init")
+"""
+
+
+_RAISES_ONLY_AT_COMPILE_TIME = """
+def _mutation_control_patch_quiet_until_compile(phase = "post_compile"):
+ # The shape the import-only gate could not see: the same phase test the two
+ # real phase-aware patches use, with a body that no longer works.
+ if phase != "post_compile": return
+ raise AttributeError("mutation control: this compile-time patch is broken")
+
+_utils.TEMPORARY_PATCHES.append(_mutation_control_patch_quiet_until_compile)
+_utils._run_temporary_patches("init")
+_utils._run_temporary_patches("post_compile")
+"""
+
+
+def test_mutation_control_a_patch_that_only_breaks_at_compile_time_turns_the_gate_red():
+ report = _collect(injection = _RAISES_ONLY_AT_COMPILE_TIME)
+ assert (
+ "_mutation_control_patch_quiet_until_compile" in report["init"]["completed"]
+ ), "the control has to be quiet during import, or it proves nothing about the compile passes"
+ with pytest.raises(AssertionError) as caught:
+ _assert_no_patch_raised(report)
+ message = str(caught.value)
+ assert "_mutation_control_patch_quiet_until_compile" in message, message
+ assert "phase post_compile" in message, message
+
+
+def test_mutation_control_a_raising_patch_turns_the_gate_red():
+ report = _collect(injection = _RAISES)
+ with pytest.raises(AssertionError) as caught:
+ _assert_no_patch_raised(report)
+ message = str(caught.value)
+ assert "_mutation_control_patch_that_raises" in message, message
+ assert "SyntaxError" in message, message
+
+
+def test_mutation_control_a_cleanly_declining_patch_does_not():
+ report = _collect(injection = _DECLINES)
+ _assert_no_patch_raised(report)
+ assert (
+ "_mutation_control_patch_that_declines" in report["init"]["completed"]
+ ), "a patch that declined cleanly was not recorded as completed"
+
+
+# ---------------------------------------------- the recording itself
+# Fast, no import of unsloth: the function is loaded out of the file the way
+# tests/test_import_time_floors.py does, so these run everywhere including a
+# host that cannot import the model stack at all.
+
+
+class _CollectingLogger:
+ def __init__(self):
+ self.warnings = []
+
+ def warning(self, message):
+ self.warnings.append(message)
+
+
+def _isolated(patches, logger, outcomes):
+ source = _UTILS.read_text(encoding = "utf-8")
+ tree = ast.parse(source)
+ for node in tree.body:
+ if isinstance(node, ast.FunctionDef) and node.name == "_run_temporary_patches":
+ segment = ast.get_source_segment(source, node)
+ break
+ else:
+ raise AssertionError("_run_temporary_patches is gone from unsloth/models/_utils.py")
+ namespace = {
+ "TEMPORARY_PATCHES": patches,
+ "logger": logger,
+ "TEMPORARY_PATCH_OUTCOMES": outcomes,
+ }
+ exec(compile(segment, str(_UTILS), "exec"), namespace)
+ return namespace["_run_temporary_patches"]
+
+
+def test_outcomes_separate_raising_from_returning():
+ def declines():
+ return None
+
+ def explodes():
+ raise RuntimeError("boom")
+
+ outcomes = {}
+ logger = _CollectingLogger()
+ _isolated([declines, explodes], logger, outcomes)("init")
+
+ assert [p.__name__ for p in outcomes["init"]["completed"]] == ["declines"]
+ assert [p.__name__ for p, _ in outcomes["init"]["raised"]] == ["explodes"]
+ assert len(logger.warnings) == 1, "fail-soft logging must be unchanged"
+
+
+def test_outcomes_are_recorded_per_phase():
+ def declines(phase):
+ return None
+
+ outcomes = {}
+ run = _isolated([declines], _CollectingLogger(), outcomes)
+ run("init")
+ run("pre_compile")
+
+ assert sorted(outcomes) == ["init", "pre_compile"]
+
+
+def test_a_repeated_pass_replaces_rather_than_grows_its_phase():
+ # `_run_temporary_patches` runs again on every model load, so an appending
+ # record would be a leak in a long-lived process.
+ def declines():
+ return None
+
+ outcomes = {}
+ run = _isolated([declines], _CollectingLogger(), outcomes)
+ for _ in range(5):
+ run("pre_compile")
+
+ assert len(outcomes["pre_compile"]["completed"]) == 1
+
+
+def test_a_recorded_failure_does_not_pin_the_frames_it_raised_from():
+ # The count check above uses a patch that returns cleanly, which is the
+ # cheap half of the question. The half that can cost memory is a patch that
+ # RAISES: `raised` stores the exception object, an exception carries its
+ # __traceback__, and a traceback keeps every frame in it and every local in
+ # those frames alive. Measured before the trim went in: the raising frame's
+ # local stayed reachable for as long as the phase entry lived, and the
+ # "init" entry is written once per process and never replaced, so an
+ # import-time failure pinned them until the process ended.
+ class _Held:
+ pass
+
+ probes = []
+
+ def explodes():
+ heavy = _Held()
+ # A weak reference, so the probe itself is not what keeps `heavy` alive.
+ probes.append(weakref.ref(heavy))
+ raise RuntimeError("boom")
+
+ outcomes = {}
+ run = _isolated([explodes], _CollectingLogger(), outcomes)
+ run("init")
+
+ patch, exception = outcomes["init"]["raised"][0]
+ assert patch is explodes
+ assert isinstance(exception, RuntimeError), "the exception itself must still be recorded"
+ assert str(exception) == "boom", "the message the gate reports must survive the trim"
+ assert exception.__traceback__ is None, (
+ "the recorded exception still carries its traceback, which keeps the failed patch's "
+ "frames and their locals alive for the lifetime of the phase entry"
+ )
+
+ # And the frame's local really is gone, not merely unreachable through the
+ # attribute that was cleared.
+ gc.collect()
+ assert probes[0]() is None, (
+ "an object local to the failed patch is still alive after the pass, so the record "
+ "is pinning the raising frame"
+ )
+
+
+def test_an_exception_that_refuses_the_trim_does_not_break_the_pass():
+ # __traceback__, __context__ and __cause__ are ordinary settable attributes,
+ # and a subclass can shadow them with a property that refuses the write.
+ # This loop runs inside `import unsloth`, so the trim must never be the thing
+ # that ends the import.
+ class _Stubborn(Exception):
+ @property
+ def __traceback__(self):
+ return None
+
+ @__traceback__.setter
+ def __traceback__(self, value):
+ raise ValueError("this exception will not give up its traceback")
+
+ def explodes():
+ raise _Stubborn("boom")
+
+ def runs_after():
+ return None
+
+ outcomes = {}
+ logger = _CollectingLogger()
+ _isolated([explodes, runs_after], logger, outcomes)("init")
+
+ assert [p.__name__ for p, _ in outcomes["init"]["raised"]] == ["explodes"]
+ assert [p.__name__ for p in outcomes["init"]["completed"]] == ["runs_after"]
+ assert len(logger.warnings) == 1
+
+
+def test_an_unnamed_callable_does_not_break_the_recording():
+ # The success path stores the callable itself and formats nothing, so a
+ # callable with no __name__ cannot make the bookkeeping raise inside
+ # `import unsloth`.
+ class _Callable:
+ def __call__(self):
+ return None
+
+ outcomes = {}
+ logger = _CollectingLogger()
+ _isolated([_Callable()], logger, outcomes)("init")
+
+ assert len(outcomes["init"]["completed"]) == 1
+ assert logger.warnings == []
+
+
+def test_the_recording_is_wired_into_the_patch_loop():
+ # DRIFT: the gate is only as good as its wiring, and a refactor that drops
+ # these lines would leave every test above green while recording nothing.
+ source = _UTILS.read_text(encoding = "utf-8")
+ tree = ast.parse(source)
+ for node in tree.body:
+ if isinstance(node, ast.FunctionDef) and node.name == "_run_temporary_patches":
+ segment = ast.get_source_segment(source, node)
+ break
+ else:
+ raise AssertionError("_run_temporary_patches is gone from unsloth/models/_utils.py")
+
+ assert "TEMPORARY_PATCH_OUTCOMES[phase]" in segment
+ assert "raised.append(" in segment
+ assert "completed.append(" in segment
+ assert (
+ "TEMPORARY_PATCH_OUTCOMES = {}" in source
+ ), "the module level record the gate reads is gone"
diff --git a/unsloth/models/_utils.py b/unsloth/models/_utils.py
index 1484ec5429a..9df944f352a 100644
--- a/unsloth/models/_utils.py
+++ b/unsloth/models/_utils.py
@@ -911,8 +911,28 @@ def resolve_encoder_attention_implementation(
return None
+# Outcome of the most recent `_run_temporary_patches` pass, keyed by phase, as
+# {"completed": [patch, ...], "raised": [(patch, exception), ...]}. A temporary
+# patch that raises is warned about rather than propagated, so without this a
+# whole patch silently dropping out leaves CI green; the regression gate in
+# tests/test_temporary_patch_coverage.py reads it and fails on a non-empty
+# "raised" bucket. Which patches legitimately decline depends on the installed
+# transformers/TRL/PEFT, so only "raised" is a defect, never the membership of
+# "completed".
+TEMPORARY_PATCH_OUTCOMES = {}
+
+
def _run_temporary_patches(phase):
import inspect
+
+ # Bookkeeping is one list append per patch, storing the callables as they
+ # are so nothing is formatted on the success path, and the per-phase entry
+ # is replaced rather than extended so repeated model loads cannot grow it.
+ # Nothing here can raise, which matters because this loop runs inside
+ # `import unsloth`.
+ completed = []
+ raised = []
+ TEMPORARY_PATCH_OUTCOMES[phase] = {"completed": completed, "raised": raised}
for temporary_patch in TEMPORARY_PATCHES:
# Two separate questions, kept separate. inspect.signature raises
# ValueError or TypeError for a callable whose signature it cannot read,
@@ -933,12 +953,34 @@ def _run_temporary_patches(phase):
else:
temporary_patch()
except Exception as exception:
+ # Keep the exception, drop what it drags along. An exception holds
+ # its __traceback__, and a traceback holds every frame in it and
+ # every local in those frames; __context__ and __cause__ chain to
+ # more of the same. The "init" entry is written once per process and
+ # never replaced, so recording a failure as-is would pin the failed
+ # patch's frames for the lifetime of the process. Nothing reads them
+ # (the gate and the warning below both use only the type and the
+ # message), so this loses no diagnosis and bounds the record to the
+ # exception objects themselves.
+ # Guarded because these three are ordinary settable attributes and a
+ # subclass can shadow them with a property that refuses the write
+ # (measured: a ValueError out of a __traceback__ setter). Losing the
+ # trim is fine; losing the import over bookkeeping is not.
+ try:
+ exception.__traceback__ = None
+ exception.__context__ = None
+ exception.__cause__ = None
+ except Exception:
+ pass
+ raised.append((temporary_patch, exception))
logger.warning(
f"Unsloth: temporary patch "
f"{getattr(temporary_patch, '__name__', temporary_patch)} failed in "
f"phase {phase} and was skipped. "
f"({type(exception).__name__}: {exception})"
)
+ else:
+ completed.append(temporary_patch)
_run_temporary_patches("init")