mudler/LocalAI · error · ValueError

unknown engine_args key {key!r}.{hint}

Error message

unknown engine_args key {key!r}.{hint}

What it means

Raised by _apply_engine_args when a key in the model YAML's engine_args JSON object does not match any field of the vllm AsyncEngineArgs dataclass (checked via dataclasses.fields). The backend uses difflib.get_close_matches to add a 'did you mean X?' hint for near-misses, so typos are usually self-diagnosing.

Source

Thrown at backend/python/vllm/backend.py:146

        Unknown keys raise ValueError with the closest valid field as a hint.
        """
        if not engine_args_json:
            return engine_args
        try:
            extra = json.loads(engine_args_json)
        except json.JSONDecodeError as e:
            raise ValueError(f"engine_args is not valid JSON: {e}") from e
        if not isinstance(extra, dict):
            raise ValueError(
                f"engine_args must be a JSON object, got {type(extra).__name__}"
            )
        valid = {f.name for f in dataclasses.fields(type(engine_args))}
        for key in extra:
            if key not in valid:
                suggestion = difflib.get_close_matches(key, valid, n=1)
                hint = f" did you mean {suggestion[0]!r}?" if suggestion else ""
                raise ValueError(f"unknown engine_args key {key!r}.{hint}")
        return dataclasses.replace(engine_args, **extra)

    def _messages_to_dicts(self, messages):
        """Convert proto Messages to list of dicts suitable for apply_chat_template()."""
        result = []
        for msg in messages:
            d = {"role": msg.role, "content": msg.content or ""}
            if msg.name:
                d["name"] = msg.name
            if msg.tool_call_id:
                d["tool_call_id"] = msg.tool_call_id
            if msg.reasoning_content:
                d["reasoning_content"] = msg.reasoning_content
            if msg.tool_calls:
                try:
                    tool_calls = json.loads(msg.tool_calls)
                except json.JSONDecodeError:
                    pass

View on GitHub (pinned to 44413a9d06)

Solutions

1. Read the hint in the error — if present, rename the key to the suggested field name
2. Convert CLI-style flags to dataclass names: --tensor-parallel-size becomes tensor_parallel_size
3. Check the installed vLLM version's AsyncEngineArgs fields (python -c "import dataclasses,vllm.engine.arg_utils as a; print([f.name for f in dataclasses.fields(a.AsyncEngineArgs)])") and keep only keys present there
4. Upgrade/align the vLLM version in backend/python/vllm/requirements so the field exists

Example fix

# before
engine_args: '{"trustremotecode": true}'
# after
engine_args: '{"trust_remote_code": true}'

import dataclasses, json
from vllm.engine.arg_utils import AsyncEngineArgs
valid = {f.name for f in dataclasses.fields(AsyncEngineArgs)}
extras = json.loads(model_config['engine_args'])
bad = [k for k in extras if k not in valid]

def unknown_engine_args_keys(engine_args_json: str) -> list[str]:
    valid = {f.name for f in dataclasses.fields(AsyncEngineArgs)}
    try:
        extras = json.loads(engine_args_json)
    except json.JSONDecodeError:
        return []
    return [k for k in extras if not isinstance(extras, dict) or k not in valid]

try:
    backend.load(request)
except ValueError as e:
    if 'unknown engine_args key' in str(e):
        # error already carries a 'did you mean' hint; act on it
        apply_hint_and_retry(str(e))
    else:
        raise

When it happens

Trigger: engine_args containing keys like "trustremotecode" (missing underscores), "tensor_parallel" instead of tensor_parallel_size, or keys that only exist in a different vLLM version's EngineArgs. Any key not in the field set of the installed vLLM's AsyncEngineArgs raises with the suggestion hint.

Common situations: Version skew: an option valid in newer vLLM (e.g. enable_prefix_caching shapes changed across releases) used against an older pinned vLLM; typo'd field names; copying engine_args from a vLLM CLI example that uses CLI flags (dashes) instead of dataclass field names (underscores).

Related errors

• engine_args must be a JSON object, got {type(extra).__name__
• trellis2 ABI mismatch: library reports %d, backend built for
• {raw!r} is not a boolean
• unknown engine_args key {key!r}.{hint}
• config.json not found under {model_path}

AI-assisted analysis of mudler/LocalAI@44413a9d06 (2026-08-15). Data as JSON: /api/errors/fea33f8446d69fdf. Report an issue: GitHub.