mudler/LocalAI · error · ValueError

unknown engine_args key

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.

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
• engine_args must be a JSON object, got
• base_model must point to a LongCat-Video checkpoint
• must be a number
• must be an integer

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

Appendix: 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)