sgl-project/sglang · error · ValueError

: not model-overridable; declarations are limited to the…

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.

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
Defensive patterns

Strategy: type-guard

Validate before calling

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}

Type guard

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

Try / catch

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

Prevention

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


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

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