sgl-project/sglang · error · ValueError

{}: {} not model-overridable; declarations are limited to th

Error message

{}: {} not model-overridable; declarations are limited to the fields the publish gate accepts.

What it means

Model-level override declarations in SGLang are restricted to fields the publish gate accepts (resolvable_fields of the ServerArgs dataclass). Declaring an unknown or non-overridable field raises this error naming the offending source and keys.

Source

Thrown at python/sglang/srt/arg_groups/overrides.py:2991

def validate_declarations(
    server_args: Any,
    declarations: Sequence[Tuple[str, Dict[str, Any]]],
) -> None:
    """Fail-fast whitelist check at declaration time: a registry typo or a
    not-yet-resolvable field must be rejected at its slot, not only at
    publish time. Declarations never mutate ``server_args``.
    """
    # Non-dataclass fixtures carry no Arg metadata (mirrors the
    # resolvable_fields escape); only real ServerArgs is validated.
    if not dataclasses.is_dataclass(type(server_args)):
        return
    whitelist = resolvable_fields(type(server_args))
    for source, decl in declarations:
        unknown = set(decl) - whitelist
        if unknown:
            raise ValueError(
                f"{source}: {sorted(unknown)} not model-overridable; "
                "declarations are limited to the fields the publish gate "
                "accepts."
            )


@register_post_process
def _hrm_text_attention_force(view: Any) -> dict:
    """HRM-Text's bidirectional prefix attention only works on the Triton
    backend. Invoked as the last attention declaration of the resolution
    (mirroring the legacy runner-side force, which ran after the whole
    pipeline)."""
    if view.attention_backend not in (None, "triton"):
        logger.warning(
            f"Overriding --attention-backend "
            f"{view.attention_backend!r} -> 'triton': only the "
            "Triton backend supports HRM-Text's bidirectional prefix "
            "attention."

View on GitHub (pinned to 0132848349)

Solutions

1. Remove the unknown key from the declaration or fix the typo
2. If the field should be model-overridable, add it to the publish gate so resolvable_fields includes it
3. Check sorted(unknown) in the message to see exactly which keys failed

from sglang.srt.arg_groups.overrides import resolvable_fields
whitelist = resolvable_fields(ServerArgs)
decl = {k: v for k, v in decl.items() if k in whitelist}

def is_valid_declaration(decl: dict, server_args_cls) -> bool:
    return set(decl) <= resolvable_fields(server_args_cls)

try:
    declare(...)
except ValueError as e:
    log.warning(f"skipping invalid override declaration: {e}")

When it happens

Trigger: Calling the declaration API with a dict containing keys that are not in resolvable_fields(ServerArgs), e.g. declaring a computed/runtime-only field as model-overridable.

Common situations: Adding a new ServerArgs field and its override declaration in the same change but forgetting the publish-gate registration; renaming a field without updating declarations; typos in declaration keys.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Unknown serve backend {name!r}. Available values: {available
• Multiple distributions register serve backend {name!r}: {pro
• Failed to load serve backend {name!r} from {self._entry_poin
• Serve backend {name!r} factory returned {type(backend).__nam
• Serve backend {name!r} uses API version {backend.api_version

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