sgl-project/sglang · error · ValueError

Unknown config key {key!r}. Valid keys: {sorted(defaults)}

Error message

Unknown config key {key!r}. Valid keys: {sorted(defaults)}

What it means

Raised when a kv pair's key does not match any dataclass field of the config class. from_kv_pairs validates keys against the set of dataclass fields (with defaults) before parsing values, and lists the valid keys in the message. This catches misspelled or outdated config option names.

Source

Thrown at python/sglang/srt/debug_utils/dumper.py:116

    def from_kv_pairs(cls, pairs: Optional[List[str]]) -> "_BaseConfig":
        return cls(**cls._kv_pairs_to_dict(pairs))

    @classmethod
    def _kv_pairs_to_dict(cls, pairs: Optional[List[str]]) -> dict:
        if not pairs:
            return {}

        missing = object()
        defaults = {f.name: f.default for f in fields(cls)}
        result: dict = {}

        for pair in pairs:
            key, sep, value = pair.partition("=")
            if not sep:
                raise ValueError(f"Invalid config pair (missing '='): {pair!r}")
            default = defaults.get(key, missing)
            if default is missing:
                raise ValueError(
                    f"Unknown config key {key!r}. Valid keys: {sorted(defaults)}"
                )
            try:
                result[key] = cls._parse_env_value(value, default)
            except (ValueError, TypeError) as exc:
                field_type = type(default).__name__
                raise TypeError(f"{key}: expected {field_type}, got {value!r}") from exc

        return result


_DEFAULT_EXP_NAME_PREFIX = "dump_"


@dataclass(frozen=True)
class DumperConfig(_BaseConfig):
    enable: bool = False
    filter: Optional[str] = None

View on GitHub (pinned to 0132848349)

Solutions

1. Read the error message: it prints the sorted list of valid keys
2. Fix the spelling / rename of the offending key
3. Re-generate your config list from the current dataclass fields (e.g. via dataclasses.fields) after upgrading sglang

Example fix

// before
cfg = DumpConfig.from_kv_pairs(["phase=decode", "phaze=prefill"])
// after
cfg = DumpConfig.from_kv_pairs(["phase=decode", "phase=prefill"])

from dataclasses import fields
valid = {f.name for f in fields(DumpConfig)}
keys = [p.partition("=")[0] for p in pairs]
unknown = [k for k in keys if k not in valid]
assert not unknown, f"unknown keys {unknown}, valid: {sorted(valid)}"

try:
    cfg = DumpConfig.from_kv_pairs(pairs)
except ValueError as e:
    if "Unknown config key" in str(e):
        # message lists valid keys; surface to user
        ...

When it happens

Trigger: Calling from_kv_pairs(['phasee=decode']) where 'phasee' is not a field of the config dataclass; using a key removed or renamed in a newer sglang version.

Common situations: Typos in option names, stale scripts written against an older field set after the dumper config schema changed, copy-pasting options from another tool's docs.

Related errors

• Invalid threshold_type for topk: {threshold_type}. Choose 'q
• Invalid threshold_type: {threshold_type}. Choose 'query_head
• Unknown cache_dit_params keys: {sorted(unknown)}. Valid keys
• f"Unknown feature map: {feature_map}"
• f"Unsupported patch_size type: {type(patch_size)}"

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