vllm-project/vllm · error · ValueError

{field_path} is not a valid config field

Error message

{field_path} is not a valid config field

What it means

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.

Source

Thrown at vllm/config/utils.py:242

class SupportsMetricsInfo(Protocol):
    def metrics_info(self) -> dict[str, str]: ...


def update_config(config: ConfigT, overrides: Mapping[str, Any]) -> ConfigT:
    return _update_config(config, overrides, type(config).__name__)


def _update_config(
    config: ConfigT, overrides: Mapping[str, Any], config_path: str
) -> ConfigT:
    processed_overrides: dict[str, Any] = {}
    field_types = get_type_hints(type(config))
    for field_name, value in overrides.items():
        field_path = f"{config_path}.{field_name}"
        if not hasattr(config, field_name):
            raise ValueError(f"{field_path} is not a valid config field")

        current_value = getattr(config, field_name)
        if is_dataclass(current_value):
            expected_type = field_types[field_name]
            if isinstance(value, Mapping):
                value = _update_config(
                    current_value,  # type: ignore[type-var]
                    value,
                    field_path,
                )
            elif not isinstance(value, expected_type):
                expected_type_name = getattr(
                    expected_type, "__name__", str(expected_type)
                )
                raise ValueError(
                    f"Override for {field_path} must be a mapping or "
                    f"{expected_type_name}, got {type(value).__name__}"
                )

View on GitHub (pinned to c794754062)

Solutions

1. Check the field exists: inspect the dataclass (e.g. dataclasses.fields(VllmConfig) or the target sub-config) and correct the field name
2. 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)
3. After a vLLM upgrade, diff your override JSON against the current config dataclasses for removed/renamed keys

Example fix

# before
update_config(cfg, {"max_num_batched_token": 8192})
# after
update_config(cfg, {"max_num_batched_tokens": 8192})

import dataclasses
def check_override_keys(config, overrides):
    bad = [k for k in overrides if not hasattr(config, k)]
    if bad:
        raise KeyError(f"unknown config fields: {bad}; "
                       f"valid: {[f.name for f in dataclasses.fields(config)]}")
    return overrides

def valid_override_keys(config, overrides: dict) -> bool:
    return all(hasattr(config, k) for k in overrides)

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Override for {field_path} must be a mapping or {expected_typ
• tool_choice function `{name}` was not found in the available
• generate request `{request_id}` has an empty prompt_token_id
• invalid method {method!r}, must be 'quest' or 'abs_max'
• The model is not multimodal.

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