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 the sglang backend's engine-args parser when a key in the engine_args JSON object does not match any field of sglang's ServerArgs dataclass. Keys are validated up front against dataclasses.fields(ServerArgs) so typos fail fast with a difflib close-match hint (e.g. 'tp_sizee' -> did you mean 'tp_size'?) instead of a TypeError during engine startup.

Source

Thrown at backend/python/sglang/backend.py:135

        early with a close-match suggestion instead of producing a confusing
        ``TypeError`` deep inside engine startup.
        """
        if not engine_args_json:
            return engine_kwargs
        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(ServerArgs)}
        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}")
        engine_kwargs.update(extra)
        return engine_kwargs

    def _messages_to_dicts(self, messages) -> List[dict]:
        result: List[dict] = []
        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. Rename the key to the suggested close match shown in the error hint
2. Check the ServerArgs fields for your installed sglang version: python -c 'import dataclasses, sglang; print([f.name for f in dataclasses.fields(sglang.ServerArgs)])'
3. Remove keys not supported by your sglang version

Example fix

# before
engine_args: '{"tensor_para_size": 2}'

# after
engine_args: '{"tp_size": 2}'

import dataclasses, json, sglang
valid = {f.name for f in dataclasses.fields(sglang.ServerArgs)}
extra = json.loads(cfg['engine_args'])
unknown = [k for k in extra if k not in valid]
if unknown:
    raise ValueError(f'keys not in ServerArgs: {unknown}; valid e.g. {sorted(valid)[:10]}')

def engine_args_keys_valid(s: str) -> bool:
    try:
        return set(json.loads(s)) <= {f.name for f in dataclasses.fields(ServerArgs)}
    except (TypeError, json.JSONDecodeError):
        return False

try:
    kwargs = _apply_engine_args(base, engine_args_json)
except ValueError as err:
    fail_config(str(err))  # message includes the did-you-mean hint

When it happens

Trigger: Including a key like 'tensor_para_size' (vllm naming) instead of 'tp_size' (sglang naming), or passing an option that exists in a different sglang version's ServerArgs.

Common situations: Copying vllm engine_args into an sglang model config, version drift where ServerArgs fields were renamed/removed, or camelCase vs snake_case mistakes.

Related errors

• engine_args is not valid JSON: {e}
• engine_args must be a JSON object, got {type(extra).__name__
• onnx_direct engine requires both detector_onnx and recognize
• unknown engine: {name!r}
• resolution must be 480p or 720p

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