sgl-project/sglang · error · ValueError

batching config rule from {source} contains unknown key(s):

Error message

batching config rule from {source} contains unknown key(s): {', '.join(hints)}

What it means

Each rule object may only contain the known BatchingRule keys; _validate_rule_keys collects unknown keys (with difflib 'did you mean' suggestions) and raises listing all of them, prefixed by the config file path.

Source

Thrown at python/sglang/multimodal_gen/runtime/managers/dynamic_batch_admission.py:320

    raise ValueError(
        "batching config must be a {'schema_version': 1, 'rules': [...]} object, "
        "a list of rules, or a mapping keyed by model|resolution"
    )


def _validate_rule_keys(data: dict[str, Any], *, source: str) -> None:
    unknown = sorted(set(data) - _BATCHING_RULE_KEYS)
    if not unknown:
        return

    hints = []
    for key in unknown:
        matches = get_close_matches(key, _BATCHING_RULE_KEYS, n=1)
        if matches:
            hints.append(f"{key!r} (did you mean {matches[0]!r}?)")
        else:
            hints.append(repr(key))
    raise ValueError(
        f"batching config rule from {source} contains unknown key(s): "
        f"{', '.join(hints)}"
    )


def _optional_str(value: Any) -> str | None:
    if value is None:
        return None
    return str(value)


def _optional_float(value: Any) -> float | None:
    if value is None:
        return None
    return float(value)


def _optional_bool(value: Any) -> bool | None:

View on GitHub (pinned to 0132848349)

Solutions

1. Rename or remove the unknown keys per the did-you-mean hints in the message
2. Check _BATCHING_RULE_KEYS in dynamic_batch_admission.py for the exact supported key set of your installed version

Example fix

// before
{"model": "x", "max_batch": 4}
// after
{"model": "x", "max_batch_size": 4}

KNOWN = {"model","model_contains","resolution","device_memory_gb_min","device_memory_gb_max","max_batch_size","max_cost"}
for i, r in enumerate(rules):
    unknown = set(r) - KNOWN
    if unknown:
        raise SystemExit(f"rule[{i}] unknown keys: {sorted(unknown)}")

When it happens

Trigger: A rule containing a misspelled or unsupported key, e.g. "max_batch" instead of "max_batch_size", or a legacy key removed from _BATCHING_RULE_KEYS.

Common situations: Typos in hand-edited configs; keys valid in a different/newer schema version; copy-paste from docs that are out of sync with the installed version.

Related errors

• Unknown cache_dit_params keys: {sorted(unknown)}. Valid keys
• batching config rule from {source} must be an object, got {t
• batching config rule requires max_batch_size
• batching config rule cannot set both model and model_contain
• batching config rule requires model or model_contains

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/bf6311dbe67850cc. Report an issue: GitHub.