sgl-project/sglang · error · ValueError

Unknown cache_dit_params keys: {sorted(unknown)}. Valid keys

Error message

Unknown cache_dit_params keys: {sorted(unknown)}. Valid keys: {sorted(CACHE_DIT_REQUEST_PARAM_KEYS)}.

What it means

resolve_cache_dit_request_overrides computes unknown = set(raw) - CACHE_DIT_REQUEST_PARAM_KEYS and rejects any top-level key not in that allowlist, listing both the offending keys and the valid set. This prevents silently ignored typos in per-request cache-dit tuning.

Source

Thrown at python/sglang/multimodal_gen/runtime/cache/cache_dit_integration.py:231

        "scm_compute_bins",
        "scm_cache_bins",
        "scm_policy",
    }
)
CACHE_DIT_REQUEST_PARAM_KEYS = (
    CACHE_DIT_REQUEST_KNOB_KEYS | CACHE_DIT_REQUEST_SCM_KEYS | {"secondary"}
)


def resolve_cache_dit_request_overrides(raw: dict | None) -> dict:
    """Validate cache_dit_params and return a copy; unknown keys fail the request."""
    if raw is None:
        return {}
    if not isinstance(raw, dict):
        raise ValueError(f"cache_dit_params must be a dict, got {type(raw).__name__}.")
    unknown = set(raw) - CACHE_DIT_REQUEST_PARAM_KEYS
    if unknown:
        raise ValueError(
            f"Unknown cache_dit_params keys: {sorted(unknown)}. "
            f"Valid keys: {sorted(CACHE_DIT_REQUEST_PARAM_KEYS)}."
        )
    overrides = dict(raw)
    secondary = overrides.get("secondary")
    if secondary is not None:
        if not isinstance(secondary, dict):
            raise ValueError(
                "cache_dit_params['secondary'] must be a dict, got "
                f"{type(secondary).__name__}."
            )
        unknown = set(secondary) - CACHE_DIT_REQUEST_KNOB_KEYS
        if unknown:
            raise ValueError(
                f"Unknown cache_dit_params['secondary'] keys: {sorted(unknown)}. "
                f"Valid keys: {sorted(CACHE_DIT_REQUEST_KNOB_KEYS)}."
            )
        overrides["secondary"] = dict(secondary)

View on GitHub (pinned to 0132848349)

Solutions

1. Use only the valid keys printed in the error message (CACHE_DIT_REQUEST_PARAM_KEYS).
2. Put secondary-knob overrides under the nested 'secondary' key, not at top level.
3. Re-check CACHE_DIT_REQUEST_PARAM_KEYS in your sglang version's cache_dit_integration.py after upgrading.

Example fix

// before
request(cache_dit_params={"secondary_cfg": 1.0})
// after
request(cache_dit_params={"secondary": {"cfg": 1.0}})

from sglang.multimodal_gen.runtime.cache.cache_dit_integration import CACHE_DIT_REQUEST_PARAM_KEYS
bad = set((cache_dit_params or {})) - CACHE_DIT_REQUEST_PARAM_KEYS
assert not bad, f"unknown keys: {bad}"
client.generate(prompt, cache_dit_params=cache_dit_params)

def valid_top_level_keys(params: dict) -> bool:
    return set(params) <= CACHE_DIT_REQUEST_PARAM_KEYS

try:
    client.generate(prompt, cache_dit_params=params)
except ValueError as e:
    if "Unknown cache_dit_params keys" in str(e):
        params = {k: v for k, v in params.items() if k in CACHE_DIT_REQUEST_PARAM_KEYS}
        retry(client.generate, prompt, cache_dit_params=params)
    raise

When it happens

Trigger: Sending cache_dit_params containing a key not in CACHE_DIT_REQUEST_PARAM_KEYS, e.g. {"num_step": 4} (typo) or {"secondary_cfg": 1.0} (flattened instead of nested under 'secondary').

Common situations: Typos or renamed keys after a version upgrade; assuming server-level CacheDitConfig field names are accepted per-request; flattening the nested 'secondary' dict to top level.

Related errors

• cache_dit_params must be a dict, got {type(raw).__name__}.
• Unknown cache_dit_params['secondary'] keys: {sorted(unknown)
• cache_dit_params['secondary'] must be a dict, got {type(seco
• batching config rule from {source} contains unknown key(s):
• Unknown config key {key!r}. Valid keys: {sorted(defaults)}

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