[Bug]: EAGLE speculative decoding crashes for multimodal wrapper architectures — load_eagle_model resolves lm_head from target_model instead of target_language_model

[benmcconaghy-art]

Your current environment

The output of python collect_env.py

Collecting environment information...
==============================
        System Info
==============================
OS                           : AlmaLinux 10.2 (Lavender Lion) (x86_64)
GCC version                  : (GCC) 14.3.1 20251022 (Red Hat 14.3.1-4)
Clang version                : Could not collect
CMake version                : Could not collect
Libc version                 : glibc-2.39

==============================
       PyTorch Info
==============================
PyTorch version              : 2.11.0+cu130
Is debug build               : False
CUDA used to build PyTorch   : 13.0
ROCM used to build PyTorch   : N/A
XPU used to build PyTorch    : N/A

==============================
      Python Environment
==============================
Python version               : 3.12.13 (main, Apr 16 2026, 00:00:00) [GCC 14.3.1 20251022 (Red Hat 14.3.1-4)] (64-bit runtime)
Python platform              : Linux-6.12.0-211.22.1.el10_2.x86_64-x86_64-with-glibc2.39

==============================
       CUDA / GPU Info
==============================
Is CUDA available            : True
CUDA runtime version         : Could not collect
CUDA_MODULE_LOADING set to   :
GPU models and configuration :
GPU 0: NVIDIA RTX PRO 6000 Blackwell Workstation Edition
GPU 1: NVIDIA RTX PRO 6000 Blackwell Workstation Edition

Nvidia driver version        : 590.48.01
cuDNN version                : Could not collect
HIP runtime version          : N/A
MIOpen runtime version       : N/A
Is XNNPACK available         : True

==============================
          CPU Info
==============================
Architecture:                            x86_64
CPU op-mode(s):                          32-bit, 64-bit
Address sizes:                           52 bits physical, 57 bits virtual
Byte Order:                              Little Endian
CPU(s):                                  48
On-line CPU(s) list:                     0-47
Vendor ID:                               AuthenticAMD
BIOS Vendor ID:                          Advanced Micro Devices, Inc.
Model name:                              AMD Ryzen Threadripper 9960X 24-Cores
BIOS Model name:                         AMD Ryzen Threadripper 9960X 24-Cores           Unknown CPU @ 4.2GHz
BIOS CPU family:                         107
CPU family:                              26
Model:                                   8
Thread(s) per core:                      2
Core(s) per socket:                      24
Socket(s):                               1
Stepping:                                1
Frequency boost:                         enabled
CPU(s) scaling MHz:                      39%
CPU max MHz:                             4200.0000
CPU min MHz:                             1223.6230
BogoMIPS:                                8387.89
Flags:                                   fpu vme de pse tsc msr pae mce cx8 apic sep mtrr pge mca cmov pat pse36 clflush mmx fxsr sse sse2 ht syscall nx mmxext fxsr_opt pdpe1gb rdtscp lm constant_tsc rep_good amd_lbr_v2 nopl xtopology nonstop_tsc cpuid extd_apicid aperfmperf rapl pni pclmulqdq monitor ssse3 fma cx16 pcid sse4_1 sse4_2 x2apic movbe popcnt aes xsave avx f16c rdrand lahf_lm cmp_legacy svm extapic cr8_legacy abm sse4a misalignsse 3dnowprefetch osvw ibs skinit wdt tce topoext perfctr_core perfctr_nb bpext perfctr_llc mwaitx cpb cat_l3 cdp_l3 hw_pstate ssbd mba perfmon_v2 ibrs ibpb stibp ibrs_enhanced vmmcall fsgsbase tsc_adjust bmi1 avx2 smep bmi2 erms invpcid cqm rdt_a avx512f avx512dq rdseed adx smap avx512ifma clflushopt clwb avx512cd sha_ni avx512bw avx512vl xsaveopt xsavec xgetbv1 xsaves cqm_llc cqm_occup_llc cqm_mbm_total cqm_mbm_local user_shstk avx_vnni avx512_bf16 clzero irperf xsaveerptr rdpru wbnoinvd amd_ppin cppc arat npt lbrv svm_lock nrip_save tsc_scale vmcb_clean flushbyasid decodeassists pausefilter pfthreshold avic v_vmsave_vmload vgif x2avic v_spec_ctrl vnmi avx512vbmi umip pku ospke avx512_vbmi2 gfni vaes vpclmulqdq avx512_vnni avx512_bitalg avx512_vpopcntdq la57 rdpid bus_lock_detect movdiri movdir64b overflow_recov succor smca fsrm avx512_vp2intersect flush_l1d debug_swap amd_lbr_pmc_freeze
Virtualization:                          AMD-V
L1d cache:                               1.1 MiB (24 instances)
L1i cache:                               768 KiB (24 instances)
L2 cache:                                24 MiB (24 instances)
L3 cache:                                128 MiB (4 instances)
NUMA node(s):                            1
NUMA node0 CPU(s):                       0-47
Vulnerability Gather data sampling:      Not affected
Vulnerability Indirect target selection: Not affected
Vulnerability Itlb multihit:             Not affected
Vulnerability L1tf:                      Not affected
Vulnerability Mds:                       Not affected
Vulnerability Meltdown:                  Not affected
Vulnerability Mmio stale data:           Not affected
Vulnerability Old microcode:             Not affected
Vulnerability Reg file data sampling:    Not affected
Vulnerability Retbleed:                  Not affected
Vulnerability Spec rstack overflow:      Mitigation; Reduced Speculation
Vulnerability Spec store bypass:         Mitigation; Speculative Store Bypass disabled via prctl
Vulnerability Spectre v1:                Mitigation; usercopy/swapgs barriers and __user pointer sanitization
Vulnerability Spectre v2:                Mitigation; Enhanced / Automatic IBRS; IBPB conditional; STIBP always-on; PBRSB-eIBRS Not affected; BHI Not affected
Vulnerability Srbds:                     Not affected
Vulnerability Tsa:                       Not affected
Vulnerability Tsx async abort:           Not affected
Vulnerability Vmscape:                   Mitigation; IBPB before exit to userspace

==============================
Versions of relevant libraries
==============================
[pip3] flashinfer-python==0.6.13
[pip3] numpy==2.2.6
[pip3] nvidia-cublas==13.1.0.3
[pip3] nvidia-cublas-cu12==12.8.4.1
[pip3] nvidia-cuda-cccl==13.3.3.3.1
[pip3] nvidia-cuda-crt==13.3.33
[pip3] nvidia-cuda-cupti==13.0.85
[pip3] nvidia-cuda-cupti-cu12==12.8.90
[pip3] nvidia-cuda-nvcc==13.2.78
[pip3] nvidia-cuda-nvrtc==13.0.88
[pip3] nvidia-cuda-nvrtc-cu12==12.8.93
[pip3] nvidia-cuda-runtime==13.0.96
[pip3] nvidia-cuda-runtime-cu12==12.8.90
[pip3] nvidia-cuda-tileiras==13.2.78
[pip3] nvidia-cudnn-cu12==9.10.2.21
[pip3] nvidia-cudnn-cu13==9.19.0.56
[pip3] nvidia-cudnn-frontend==1.25.0
[pip3] nvidia-cufft==12.0.0.61
[pip3] nvidia-cufft-cu12==11.3.3.83
[pip3] nvidia-cufile==1.15.1.6
[pip3] nvidia-cufile-cu12==1.13.1.3
[pip3] nvidia-curand==10.4.0.35
[pip3] nvidia-curand-cu12==10.3.9.90
[pip3] nvidia-cusolver==12.0.4.66
[pip3] nvidia-cusolver-cu12==11.7.3.90
[pip3] nvidia-cusparse==12.6.3.3
[pip3] nvidia-cusparse-cu12==12.5.8.93
[pip3] nvidia-cusparselt-cu12==0.7.1
[pip3] nvidia-cusparselt-cu13==0.8.0
[pip3] nvidia-cutlass-dsl==4.5.2
[pip3] nvidia-cutlass-dsl-libs-base==4.5.2
[pip3] nvidia-cutlass-dsl-libs-cu13==4.5.2
[pip3] nvidia-ml-py==13.595.45
[pip3] nvidia-nccl-cu12==2.29.7
[pip3] nvidia-nccl-cu13==2.28.9
[pip3] nvidia-nvjitlink==13.0.88
[pip3] nvidia-nvjitlink-cu12==12.8.93
[pip3] nvidia-nvshmem-cu12==3.4.5
[pip3] nvidia-nvshmem-cu13==3.4.5
[pip3] nvidia-nvtx==13.0.85
[pip3] nvidia-nvtx-cu12==12.8.90
[pip3] nvidia-nvvm==13.2.78
[pip3] onnxruntime==1.24.3
[pip3] pytorch-lightning==2.6.1
[pip3] pytorch-metric-learning==2.9.0
[pip3] pyzmq==27.1.0
[pip3] tokenspeed-triton==3.7.10.post20260505
[pip3] torch==2.11.0
[pip3] torch-audiomentations==0.12.0
[pip3] torch_c_dlpack_ext==0.1.5
[pip3] torch_pitch_shift==1.2.5
[pip3] torchao==0.17.0
[pip3] torchaudio==2.11.0
[pip3] torchcodec==0.14.0
[pip3] torchmetrics==1.8.2
[pip3] torchvision==0.26.0
[pip3] transformers==5.8.1
[pip3] triton==3.6.0
[conda] Could not collect

==============================
         vLLM Info
==============================
ROCM Version                 : Could not collect
vLLM Version                 : 0.25.1
vLLM Build Flags:
  CUDA Archs: Not Set; ROCm: Disabled; XPU: Disabled
GPU Topology:
        GPU0    GPU1    CPU Affinity    NUMA Affinity   GPU NUMA ID
GPU0     X      NODE    0-47    0               N/A
GPU1    NODE     X      0-47    0               N/A

Legend:

  X    = Self
  SYS  = Connection traversing PCIe as well as the SMP interconnect between NUMA nodes (e.g., QPI/UPI)
  NODE = Connection traversing PCIe as well as the interconnect between PCIe Host Bridges within a NUMA node
  PHB  = Connection traversing PCIe as well as a PCIe Host Bridge (typically the CPU)
  PXB  = Connection traversing multiple PCIe bridges (without traversing the PCIe Host Bridge)
  PIX  = Connection traversing at most a single PCIe bridge
  NV#  = Connection traversing a bonded set of # NVLinks

==============================
     Environment Variables
==============================
PYTORCH_NVML_BASED_CUDA_CHECK=1
TORCHINDUCTOR_COMPILE_THREADS=1
TORCHINDUCTOR_CACHE_DIR=/tmp/torchinductor_root

🐛 Describe the bug

Serving a multimodal-wrapper target model (e.g. Mistral3ForConditionalGeneration, architecture mistral3) with an EAGLE draft head crashes EngineCore during profile_run. The target model loads fine; the crash is in the drafter.

Root cause: load_eagle_model() in vllm/v1/worker/gpu/spec_decode/eagle/utils.py resolves the embedding-sharing target correctly via get_language_model(), but resolves the lm_head-sharing target directly from the top-level target_model:

target_lm_head = getattr(target_model, "lm_head", None)

For multimodal wrapper architectures, lm_head does not exist on the top-level model — it lives on the inner language-model submodule (target_model.language_model.lm_head for Mistral3ForConditionalGeneration, confirmed via its hf_to_vllm_mapper: "lm_head.": "language_model.lm_head."). getattr(target_model, "lm_head", None) therefore silently returns None, the sharing block is skipped, and the draft model's EagleMistralForCausalLM.__init__ deliberately never creates its own lm_head (see comment in vllm/model_executor/models/mistral_eagle.py: "Bypass MistralForCausalLM.init to use the draft model config and to avoid creating an lm_head" — it expects load_eagle_model to inject it). The result is an AttributeError the first time the draft model's compute_logits is called.

Notably, get_language_model() is already used a few lines above in the same function to correctly resolve the embed_tokens sharing target — the lm_head lookup just doesn't go through the same resolution path.

Serve command

vllm serve <mistral3-nvfp4-checkpoint> \
  --tensor-parallel-size 2 \
  --quantization compressed-tensors \
  --tool-call-parser mistral --enable-auto-tool-choice \
  --speculative-config '{"method": "eagle", "model": "<eagle-draft-checkpoint>", "num_speculative_tokens": 3, "draft_tensor_parallel_size": 1}'

Traceback (abridged)

Worker_TP0 ... profile_run -> _dummy_run -> speculator.propose -> _prefill -> sample_draft -> _greedy_sample_draft
  File ".../model_executor/models/llama.py", line 532, in compute_logits
    logits = self.logits_processor(self.lm_head, hidden_states)
  File ".../torch/nn/modules/module.py", line 1968, in __getattr__
    raise AttributeError(...)
AttributeError: 'EagleMistralForCausalLM' object has no attribute 'lm_head'
...
RuntimeError: Worker failed with error ''EagleMistralForCausalLM' object has no attribute 'lm_head'', please check the stack trace above for the root cause

Suggested fix

In load_eagle_model(), resolve target_lm_head the same way target_embed is already resolved — falling back to the language-submodule when the top-level model doesn't have its own lm_head:

# before
target_lm_head = getattr(target_model, "lm_head", None)

# after
target_lm_head = getattr(target_model, "lm_head", None) or getattr(
    target_language_model, "lm_head", None
)

I've applied and tested this exact change locally against vllm==0.25.1 — model loads, EagleMistralForCausalLM initializes correctly, cudagraph capture for the speculator completes, and the server serves correctly with speculative decoding active.