{"record":{"id":"fadf042e40b0a0a3","repo":"vllm-project/vllm","slug":"unknown-dtype-head-dtype","errorCode":null,"errorMessage":"Unknown dtype: {head_dtype}","messagePattern":"Unknown dtype: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/config/model.py","lineNumber":2325,"sourceCode":"    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,\n    disable_sliding_window: bool,\n    sliding_window: int | None,\n    spec_target_max_model_len: int | None = None,\n    encoder_config: dict[str, Any] | None = None,\n) -> int:\n    \"\"\"Get and verify the model's maximum length.\"\"\"\n    (derived_max_model_len, max_len_key) = (\n        model_arch_config.derived_max_model_len_and_key\n    )\n\n    # If sliding window is manually disabled, max_length should be less","sourceCodeStart":2307,"sourceCodeEnd":2343,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/config/model.py#L2307-L2343","documentation":"The terminal else of _get_head_dtype: head_dtype is not None, not the string 'model', not a str, and not a torch.dtype — it is some other object type (int, list, numpy dtype), so it cannot be interpreted and raises ValueError (formatted without !r).","triggerScenarios":"config.head_dtype set to a non-string, non-torch.dtype JSON value (e.g. 16, 2, or a nested list) in the checkpoint's config.json.","commonSituations":"Hand-edited or programmatically generated config.json where head_dtype was written as a numeric code; conversion scripts mapping framework enums to JSON incorrectly.","solutions":["Fix config.json so head_dtype is one of: omitted, \"model\", a dtype name string, or absent — never a number or structure.","If per-head dtype control is unneeded, delete the field to use defaults."],"exampleFix":"// before: config.json\n\"head_dtype\": 16\n// after\n\"head_dtype\": \"float16\"","handlingStrategy":"type-guard","validationCode":"import torch\ndef valid_head_dtype_value(hd) -> bool:\n    return hd is None or hd == 'model' or isinstance(hd, (str, torch.dtype))","typeGuard":"import torch\ndef is_valid_head_dtype(hd: object) -> bool:\n    return hd is None or hd == 'model' or isinstance(hd, (str, torch.dtype))","tryCatchPattern":null,"preventionTips":["Never store numeric dtype codes in head_dtype; JSON config fields must be strings or omitted.","Validate hand-edited config.json files with a schema before serving.","Automate checkpoint post-processing so experimental head_dtype values are normalized or stripped."],"tags":["dtype","hf-config","type-error"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}