{"record":{"id":"24d9d547c7e92c0b","repo":"vllm-project/vllm","slug":"field-path-is-not-a-valid-config-field","errorCode":null,"errorMessage":"{field_path} is not a valid config field","messagePattern":"(.+?) is not a valid config field","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/config/utils.py","lineNumber":242,"sourceCode":"\n\nclass SupportsMetricsInfo(Protocol):\n    def metrics_info(self) -> dict[str, str]: ...\n\n\ndef update_config(config: ConfigT, overrides: Mapping[str, Any]) -> ConfigT:\n    return _update_config(config, overrides, type(config).__name__)\n\n\ndef _update_config(\n    config: ConfigT, overrides: Mapping[str, Any], config_path: str\n) -> ConfigT:\n    processed_overrides: dict[str, Any] = {}\n    field_types = get_type_hints(type(config))\n    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                )","sourceCodeStart":224,"sourceCodeEnd":260,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/config/utils.py#L224-L260","documentation":"The config-override utility (_update_config in vllm/config/utils.py, used by update_config and thus by --config-update / programmatic overrides) rejects any override key that is not an existing attribute on the target dataclass config. It builds the dotted path '<ConfigClassName>.<field>' and raises, protecting against typos and removed/renamed fields silently no-op'ing. Overrides are applied via dataclasses.replace only after every key passes this hasattr check.","triggerScenarios":"Calling update_config(VllmConfig(...), {\"max_model_len\": ...}) with a key that does not exist on that config object (e.g. passing a CacheConfig field to the top-level config), or passing a CLI --config-update JSON containing a stale field name removed in a vLLM upgrade.","commonSituations":"Renamed config fields across vLLM versions (override written for an older release); typos in override keys ('max_num_batched_token' missing the 's'); targeting the wrong nested config level; scripts that merge user-supplied option dicts into config overrides without validation.","solutions":["Check the field exists: inspect the dataclass (e.g. dataclasses.fields(VllmConfig) or the target sub-config) and correct the field name","Nest the override correctly — if the field lives on a sub-config, override via the mapping form so it recurses into that dataclass (e.g. {'cache_config': {'max_num_batched_tokens': ...}} depending on the API's expected shape)","After a vLLM upgrade, diff your override JSON against the current config dataclasses for removed/renamed keys"],"exampleFix":"# before\nupdate_config(cfg, {\"max_num_batched_token\": 8192})\n# after\nupdate_config(cfg, {\"max_num_batched_tokens\": 8192})","handlingStrategy":"type-guard","validationCode":"import dataclasses\ndef check_override_keys(config, overrides):\n    bad = [k for k in overrides if not hasattr(config, k)]\n    if bad:\n        raise KeyError(f\"unknown config fields: {bad}; \"\n                       f\"valid: {[f.name for f in dataclasses.fields(config)]}\")\n    return overrides","typeGuard":"def valid_override_keys(config, overrides: dict) -> bool:\n    return all(hasattr(config, k) for k in overrides)","tryCatchPattern":null,"preventionTips":["Validate override dicts against dataclasses.fields(type(config)) before calling update_config","Regenerate override JSONs from current vLLM config classes after each upgrade","Fail on unknown keys early in your config loader instead of letting vLLM reject at startup"],"tags":["config","validation","typo","api-misuse"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}