sgl-project/sglang · error · ValueError

batching config rule from

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.

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

• batching config must be a
• batching config rule cannot set both model and…
• batching config rule device_memory_gb_min must be <=…
• batching config rule from
• batching config rule max_batch_size must be >= 1

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

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