Environment variable

Error message

Environment variable {old_name} is deprecated. Please use {self.replacement} instead. {self.note}

What it means

sglang's startup env-migration found a variable listed in _DEPRECATED_ENVS. It warns, and if a replacement is defined, copies (optionally transformed) the value to the new name. The old variable keeps existing in os.environ but the canonical name is what the code reads.

Solutions

Replace the deprecated var with its replacement named in the warning message
If a transform applies, make sure your value is in the new expected format
Remove the old var from orchestration manifests and retest

Example fix

# before
export SGLANG_OLD_FLAG=xyz
# after
export SGLANG_NEW_FLAG=xyz  # name shown in the warning

Defensive patterns

Strategy: validation

Validate before calling

# before launch, assert no deprecated vars are set:
from sglang.srt.environ import _DEPRECATED_ENVS
bad = [k for k in os.environ if k in _DEPRECATED_ENVS]
assert not bad, bad

Prevention

Keep env manifests version-controlled and reviewed per release
Remove old flags when adopting replacements, don't keep both

When it happens

Trigger: Setting a deprecated variable registered in _DEPRECATED_ENVS (e.g. an old tuning flag with a renamed successor) at process start, which triggers _handle_deprecated_envs -> apply().

Common situations: Cluster scheduler YAML or container env blocks pinned to an older sglang release then upgrading; docs/blog examples using pre-rename flags.

Related errors

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

Appendix: source

Thrown at python/sglang/srt/environ.py:1616

    def __init__(
        self,
        replacement: Optional[str] = None,
        transform: Optional[Callable[[str], str]] = None,
        note: Optional[str] = None,
    ):
        self.replacement = replacement
        self.transform = transform
        self.note = note

    def apply(self, old_name: str):
        if old_name not in os.environ:
            return
        message = f"Environment variable {old_name} is deprecated."
        if self.replacement is not None:
            message += f" Please use {self.replacement} instead."
        if self.note is not None:
            message += f" {self.note}"
        warnings.warn(message)
        if self.replacement is not None:
            value = os.environ[old_name]
            if self.transform is not None:
                value = self.transform(value)
            os.environ[self.replacement] = value


def _ms_to_s(value: str) -> str:
    return str(float(value) / 1000.0)


def _invert_bool(value: str) -> str:
    return "0" if value.lower() in ("true", "1", "yes", "y") else "1"


# The single registry for deprecated environment variables, processed once at
# import by _handle_deprecated_envs(). Add new deprecations here instead of
# ad-hoc warnings. For a rename where the old name must keep working through a

View on GitHub (pinned to 0132848349)