vllm-project/vllm · error · ValueError

target_model_config must be present for dspark

Error message

target_model_config must be present for dspark

What it means

Same guard as the MTP one, but for method == 'dspark': DeepSeek DSpark draft weights may ship inside the target checkpoint, so when no separate model is given, vLLM must read the target ModelConfig to locate them. A missing target_model_config makes resolution impossible and fails immediately.

Source

Thrown at vllm/config/speculative.py:775

        if self.model is None and self.num_speculative_tokens is not None:
            if self.method == "mtp":
                if self.target_model_config is None:
                    raise ValueError("target_model_config must be present for mtp")
                if self.target_model_config.hf_text_config.model_type == "deepseek_v32":
                    # FIXME(luccafong): cudagraph with v32 MTP is not supported,
                    # remove this when the issue is fixed.
                    self.enforce_eager = True
                # use the draft model from the same model:
                self.model = self.target_model_config.model
                # Align the quantization of draft model for cases such as
                # --quantization fp8 with a bf16 checkpoint.
                if not self.quantization:
                    self.quantization = self.target_model_config.quantization
            elif self.method == "dspark":
                # DeepSeek DSpark can ship the weights inside the target checkpoint
                if self.target_model_config is None:
                    raise ValueError("target_model_config must be present for dspark")
                self.model = self.target_model_config.model
                if not self.quantization:
                    self.quantization = self.target_model_config.quantization
            elif self.method in ("ngram", "[ngram]"):
                self.model = "ngram"
            elif self.method == "ngram_gpu":
                self.model = "ngram_gpu"
            elif self.method == "suffix":
                self.model = "suffix"
            elif self.method == "extract_hidden_states":
                self.model = "extract_hidden_states"
            elif self.method == "custom_class":
                # method was set explicitly, but model should already contain the
                # custom module path. If not, this is a configuration error.
                if self.model is None:
                    raise ValueError(
                        "method='custom_class' requires 'model' to contain the "
                        "custom proposer module path (e.g., 'my_module.MyProposer')."

View on GitHub (pinned to c794754062)

Solutions

  1. Go through standard engine entrypoints so target_model_config is attached
  2. Pass target_model_config explicitly when constructing SpeculativeConfig yourself
  3. Or point model= at the DSpark draft checkpoint if you have it separately

Example fix

# before
SpeculativeConfig(method='dspark', num_speculative_tokens=2)

# after
SpeculativeConfig(method='dspark', num_speculative_tokens=2, target_model_config=target_cfg)
Defensive patterns

Strategy: validation

Validate before calling

def dspark_config_ready(cfg: 'SpeculativeConfig') -> bool:
    return not (cfg.method == 'dspark' and cfg.model is None and cfg.num_speculative_tokens is not None and cfg.target_model_config is None)

Type guard

null

Try / catch

null

Prevention

When it happens

Trigger: SpeculativeConfig(method='dspark', num_speculative_tokens=N) built without target_model_config; invoking dspark speculation through a nonstandard code path that skips attaching the target config.

Common situations: Programmatic engine construction; wrapping/re-validating SpeculativeConfig in tooling; version changes in how the engine wires target_model_config.

Related errors

AI-assisted analysis of vllm-project/vllm@c794754062 (2026-08-14). Data as JSON: /api/errors/d074438db6fe7015. Report an issue: GitHub.