sgl-project/sglang · error · ValueError

SGLANG_ROLE_NAMESPACES={value!r} is not one of off / record

Error message

SGLANG_ROLE_NAMESPACES={value!r} is not one of off / record / enforce — refusing to guess (a typo here would silently disable enforcement.)

What it means

SGLANG_ROLE_NAMESPACES must normalize (strip+lowercase) to exactly off, record, or enforce. Any other value raises this ValueError because silently treating a typo like 'enforec' as 'off' would disable namespace enforcement without warning — the check is deliberately fail-closed.

Source

Thrown at python/sglang/srt/runtime_context.py:1228

    # exercise the multimodal processors, LoRA/score endpoints, the disagg
    # roles, or the gRPC bridge; narrowing needs those shapes audited too, and
    # a wrong set fails a request rather than a test.
    "tokenizer": None,
    # Deployment shapes not exercised locally; audit before restricting.
    "detokenizer": None,
    "encoder": None,
    "expert_backup": None,
    "weight_cache_daemon": None,
    # The diffusion GPU worker runs a model and publishes a placeholder so
    # shared SRT reads do not fail closed; declared full for that reason.
    "diffusion_gpu_worker": None,
}


def _validated_role_ns_mode(value: str) -> str:
    mode = value.strip().lower()
    if mode not in ("off", "record", "enforce"):
        raise ValueError(
            f"SGLANG_ROLE_NAMESPACES={value!r} is not one of off / record / "
            "enforce — refusing to guess (a typo here would silently disable "
            "enforcement)."
        )
    return mode


def _role_ns_mode_from_env() -> str:
    # Resolved once at import so the config_bag gate stays a dynamo-prunable
    # constant; validated fail-loud here (EnvField's warn-and-default parse
    # would silently turn a typo into "off").
    from sglang.srt.environ import envs

    return _validated_role_ns_mode(envs.SGLANG_ROLE_NAMESPACES.get())


_ROLE_NS_MODE = _role_ns_mode_from_env()
_RECORDED_NS_READS: set[tuple[str | None, str]] = set()

View on GitHub (pinned to 0132848349)

Solutions

Fix the value to exactly off, record, or enforce
Check how the env var was exported — surrounding quotes or whitespace become part of the value (e.g. export VAR="enforce " keeps the space)
If you don't need role namespaces, unset the variable entirely rather than setting a wrong value

Example fix

# before
export SGLANG_ROLE_NAMESPACES="enforce "  # or a typo like enforec
# after
export SGLANG_ROLE_NAMESPACES=enforce

Defensive patterns

Strategy: validation

Validate before calling

import os
v = os.environ.get("SGLANG_ROLE_NAMESPACES")
if v is not None and v.strip().lower() not in {"off", "record", "enforce"}:
    raise ValueError("SGLANG_ROLE_NAMESPACES must be off/record/enforce")

Prevention

Set env vars in one place (deployment manifest) and validate them at startup
Avoid quoting env var values in shell exports
Prefer unsetting the var over guessing a value

When it happens

Trigger: Setting SGLANG_ROLE_NAMESPACES to a typo (e.g. 'enforec'), a boolean-ish value ('1', 'true'), or a value with stray quotes/whitespace, then triggering _validated_role_ns_mode via the env read at startup.

Common situations: Typos in deployment env vars (k8s manifests, .env files, CI yaml); stale docs recommending old values like 'true'; shell exports that leave literal quotes in the value.

Related errors

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