{"record":{"id":"14089707db7e1484","repo":"vllm-project/vllm","slug":"override-for-field-path-must-be-a-mapping-or-ex","errorCode":null,"errorMessage":"Override for {field_path} must be a mapping or {expected_type_name}, got {type(value).__name__}","messagePattern":"Override for (.+?) must be a mapping or (.+?), got (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/config/utils.py","lineNumber":257,"sourceCode":"    for field_name, value in overrides.items():\n        field_path = f\"{config_path}.{field_name}\"\n        if not hasattr(config, field_name):\n            raise ValueError(f\"{field_path} is not a valid config field\")\n\n        current_value = getattr(config, field_name)\n        if is_dataclass(current_value):\n            expected_type = field_types[field_name]\n            if isinstance(value, Mapping):\n                value = _update_config(\n                    current_value,  # type: ignore[type-var]\n                    value,\n                    field_path,\n                )\n            elif not isinstance(value, expected_type):\n                expected_type_name = getattr(\n                    expected_type, \"__name__\", str(expected_type)\n                )\n                raise ValueError(\n                    f\"Override for {field_path} must be a mapping or \"\n                    f\"{expected_type_name}, got {type(value).__name__}\"\n                )\n\n        processed_overrides[field_name] = value\n    return replace(config, **processed_overrides)\n\n\ndef normalize_value(x):\n    \"\"\"Return a stable, JSON-serializable canonical form for hashing.\n    Order: primitives, special types (Enum, callable, torch.dtype, Path), then\n    generic containers (Mapping/Set/Sequence) with recursion.\n    \"\"\"\n    # Fast path\n    if x is None or isinstance(x, (bool, int, float, str)):\n        return x\n\n    # Enums: tag with FQN to avoid primitive collisions.","sourceCodeStart":239,"sourceCodeEnd":275,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/config/utils.py#L239-L275","documentation":"When an override targets a field whose current value is a nested dataclass, _update_config requires the override value to be either a Mapping (to recursively patch the nested config) or an instance of the field's declared type. Anything else (e.g. a plain string, int, or list) is rejected with this message naming the expected type and the actual type received. This prevents accidentally replacing a structured sub-config with an incompatible primitive.","triggerScenarios":"Calling update_config with something like {'parallel_config': 4} or {'compilation_config': 'FULL'} where the field holds a ParallelConfig/CompilationConfig dataclass; passing a scalar where the declared field type is a dataclass and the value is neither a dict nor that dataclass type.","commonSituations":"Assuming override values are always scalars and writing shorthand like {'cache_config': 2048}; CLI --config-update JSONs that flatten nested settings into dotted-strings instead of nested objects; version changes that converted a formerly-scalar field into a dataclass.","solutions":["Pass a nested mapping so it recurses: update_config(cfg, {'cache_config': {'gpu_memory_utilization': 0.9}})","Or construct/replace with a full instance of the declared dataclass type if you have one","Check get_type_hints(type(config))[field_name] (or dataclasses.fields) to confirm the expected type before sending the override"],"exampleFix":"# before\nupdate_config(cfg, {\"compilation_config\": \"FULL\"})\n# after\nupdate_config(cfg, {\"compilation_config\": {\"mode\": \"FULL\"}})","handlingStrategy":"type-guard","validationCode":"import dataclasses\nfrom collections.abc import Mapping\nfrom typing import get_type_hints\ndef check_override_types(config, overrides):\n    hints = get_type_hints(type(config))\n    for k, v in overrides.items():\n        cur = getattr(config, k, None)\n        if cur is not None and dataclasses.is_dataclass(cur):\n            assert isinstance(v, Mapping) or isinstance(v, type(cur)), \\\n                f\"{k} must be a mapping or {type(cur).__name__}\"","typeGuard":"def overrides_well_typed(config, overrides: dict) -> bool:\n    hints = get_type_hints(type(config))\n    for k, v in overrides.items():\n        cur = getattr(config, k, None)\n        if dataclasses.is_dataclass(cur) and not (\n                isinstance(v, Mapping) or isinstance(v, hints.get(k, type(cur)))):\n            return False\n    return True","tryCatchPattern":null,"preventionTips":["Always express nested overrides as nested dicts, never dotted strings or scalars","Unit-test your config-update layer against the live vLLM dataclasses"],"tags":["config","validation","type-mismatch","api-misuse"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}