{"record":{"id":"40aa00504b208b82","repo":"vllm-project/vllm","slug":"unknown-dtype-head-dtype-r","errorCode":null,"errorMessage":"Unknown dtype: {head_dtype!r}","messagePattern":"Unknown dtype: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/config/model.py","lineNumber":2314,"sourceCode":"            logger.info(\"Downcasting %s to %s.\", config_dtype, torch_dtype)\n        else:\n            # Casting between float16 and bfloat16 is allowed with a warning.\n            logger.warning(\"Casting %s to %s.\", config_dtype, torch_dtype)\n\n    return torch_dtype\n\n\ndef _get_head_dtype(\n    config: PretrainedConfig, dtype: torch.dtype, runner_type: str\n) -> torch.dtype:\n    head_dtype: str | torch.dtype | None = getattr(config, \"head_dtype\", None)\n\n    if head_dtype == \"model\":\n        return dtype\n    elif isinstance(head_dtype, str):\n        head_dtype = head_dtype.lower()\n        if head_dtype not in _STR_DTYPE_TO_TORCH_DTYPE:\n            raise ValueError(f\"Unknown dtype: {head_dtype!r}\")\n        return _STR_DTYPE_TO_TORCH_DTYPE[head_dtype]\n    elif isinstance(head_dtype, torch.dtype):\n        return head_dtype\n    elif head_dtype is None:\n        if torch.float32 not in current_platform.supported_dtypes:\n            return dtype\n        if runner_type == \"pooling\":\n            return torch.float32\n        return dtype\n    else:\n        raise ValueError(f\"Unknown dtype: {head_dtype}\")\n\n\ndef _get_and_verify_max_len(\n    hf_config: PretrainedConfig,\n    model_arch_config: ModelArchitectureConfig,\n    tokenizer_config: dict | None,\n    max_model_len: int | None,","sourceCodeStart":2296,"sourceCodeEnd":2332,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/config/model.py#L2296-L2332","documentation":"_get_head_dtype reads an optional head_dtype field from the HF config to give the lm_head/pooling head a different precision than the body. A string head_dtype that is not a key of _STR_DTYPE_TO_TORCH_DTYPE (after lowercasing) raises this ValueError.","triggerScenarios":"config.head_dtype is a string like 'fp16' or 'float' that is not in the dtype table; triggered whenever ModelConfig verifies head dtypes for a runner.","commonSituations":"Fine-tuned checkpoints saved with a nonstandard head_dtype value; hand-edited config.json; model authors experimenting with per-head precision fields that vLLM only partially recognizes.","solutions":["Set head_dtype in config.json to a recognized name ('float16', 'bfloat16', 'float32') or to 'model' to inherit the body dtype.","Remove the head_dtype field entirely to fall back to the default resolution (body dtype, or fp32 for pooling where supported)."],"exampleFix":"// before: config.json\n\"head_dtype\": \"fp16\"\n// after\n\"head_dtype\": \"float16\"","handlingStrategy":"validation","validationCode":"from vllm.config.model import _STR_DTYPE_TO_TORCH_DTYPE\ndef head_dtype_ok(hd) -> bool:\n    return hd is None or hd == 'model' or (\n        isinstance(hd, str) and hd.lower() in _STR_DTYPE_TO_TORCH_DTYPE)","typeGuard":"def is_valid_head_dtype(hd: object) -> bool:\n    return hd is None or hd == 'model' or (\n        isinstance(hd, str) and hd.lower() in _STR_DTYPE_TO_TORCH_DTYPE) or (\n        isinstance(hd, __import__('torch').dtype))","tryCatchPattern":null,"preventionTips":["Only write recognized dtype names or 'model' into head_dtype in config.json.","Schema-validate checkpoint configs before deployment (head_dtype must be string or absent).","Prefer omitting head_dtype unless per-head precision is deliberately needed."],"tags":["dtype","hf-config","head","validation"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}