From 509fd4227c24c4e710eaeb0f1a37bfcf3bbae25e Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Tue, 20 Jan 2026 01:02:39 -0800
Subject: [PATCH] Handle Transformers 5 vLLM import errors (#3908)

* Handle Transformers 5 vLLM import errors

* Deduplicate vLLM transformers mismatch handling

---------

Co-authored-by: danielhanchen <danielhanchen@users.noreply.github.com>
---
 unsloth/import_fixes.py  | 31 +++++++++++++++++++++++++++++--
 unsloth/models/vision.py |  4 ++--
 2 files changed, 31 insertions(+), 4 deletions(-)

diff --git a/unsloth/import_fixes.py b/unsloth/import_fixes.py
index 89d9d4bdba..4f88808c2a 100644
--- a/unsloth/import_fixes.py
+++ b/unsloth/import_fixes.py
@@ -307,16 +307,43 @@ def fix_vllm_aimv2_issue():
 
 
 def fix_vllm_guided_decoding_params():
+    def _maybe_raise_vllm_transformers_mismatch(error):
+        error_text = str(error)
+        if (
+            "ALLOWED_LAYER_TYPES" in error_text
+            or "transformers.configuration_utils" in error_text
+        ):
+            try:
+                vllm_version = importlib_version("vllm")
+            except Exception:
+                vllm_version = "unknown"
+            raise RuntimeError(
+                "Unsloth: vLLM with version "
+                f"{vllm_version} does not yet support transformers>=5.0.0. "
+                "Please downgrade to transformers==4.57.3 via "
+                'pip install --force-reinstall "transformers==4.57.3". '
+                f"Original error: {error}"
+            ) from error
+
     if importlib.util.find_spec("vllm") is None:
         return
     # GuidedDecodingParmas is renamed to StructuredOutputsParams in vLLM
     # https://github.com/vllm-project/vllm/pull/22772/files
     # trl still wants to use GuidedDecodingParams. This is a temporary patch till trl updates
-    import vllm
+    try:
+        import vllm
+    except ImportError as e:
+        _maybe_raise_vllm_transformers_mismatch(e)
+        raise
 
     try:
         from vllm.sampling_params import GuidedDecodingParams
-    except ImportError:
+    except ImportError as e:
+        _maybe_raise_vllm_transformers_mismatch(e)
+        if not hasattr(vllm, "sampling_params") or not hasattr(
+            vllm.sampling_params, "StructuredOutputsParams"
+        ):
+            raise
         vllm.sampling_params.GuidedDecodingParams = (
             vllm.sampling_params.StructuredOutputsParams
         )
diff --git a/unsloth/models/vision.py b/unsloth/models/vision.py
index 4e03e0a168..a77cf715fc 100644
--- a/unsloth/models/vision.py
+++ b/unsloth/models/vision.py
@@ -106,7 +106,7 @@ PRE_COMPILE_INFERENCE = [
     "gpt_oss",
 ]
 
-from transformers import GenerationConfig, CompileConfig, HybridCache, AutoConfig
+from transformers import GenerationConfig, CompileConfig, AutoConfig
 
 try:
     from transformers import PreTrainedConfig
@@ -117,7 +117,7 @@ except:
 
 HAS_TORCH_DTYPE = "torch_dtype" in PretrainedConfig.__doc__
 
-from transformers import GenerationConfig, CompileConfig, HybridCache
+from transformers import GenerationConfig, CompileConfig
 
 _compile_config = CompileConfig(
     fullgraph = False,