sgl-project/sglang · error · ImportError

RayPrometheusMetric requires Ray to be installed. Install wi

Error message

RayPrometheusMetric requires Ray to be installed. Install with: pip install 'ray[serve]'

What it means

RayPrometheusMetric wraps Ray Serve's metrics API, which is only present when the ray package (with serve extras) is installed. If the ray import failed, the module-level ray_metrics is None and constructing this wrapper raises ImportError with install instructions.

Source

Thrown at python/sglang/srt/observability/ray_wrappers.py:89

    Subclasses populate ``self.metric`` with a ``ray.util.metrics`` instance in
    their ``__init__``. Shared behaviour:

    * A ``ReplicaId`` tag is appended to every metric and populated at
      instantiation (and again on each ``labels()`` call) so Ray-Serve replicas
      are distinguishable on dashboards.
    * ``labels()`` returns a fresh copy of the wrapper with its tags bound,
      mirroring the ``prometheus_client`` pattern and avoiding state sharing
      between concurrent emits.
    * Metric names are sanitised to satisfy Ray's OpenTelemetry naming rule
      (no ``:``, no other punctuation).
    """

    _is_labeled: bool = False

    def __init__(self) -> None:
        if ray_metrics is None:
            raise ImportError(
                "RayPrometheusMetric requires Ray to be installed. "
                "Install with: pip install 'ray[serve]'"
            )
        self.metric: Optional[Metric] = None
        self._tags: dict = {"ReplicaId": _get_replica_id() or ""}

    @staticmethod
    def _get_tag_keys(labelnames: Optional[List[str]]) -> tuple:
        labels = list(labelnames) if labelnames else []
        labels.append("ReplicaId")
        return tuple(labels)

    def _build_tags(self, *labels: str, **labelskwargs: str) -> dict:
        if labels:
            # The trailing entry of ``_tag_keys`` is always ``ReplicaId`` which we
            # populate ourselves; positional args fill the preceding keys only.
            expected = len(self.metric._tag_keys) - 1
            if len(labels) != expected:

View on GitHub (pinned to 0132848349)

Solutions

1. pip install 'ray[serve]' in the environment
2. Or disable the Ray metrics path / use the standard Prometheus metrics wrapper instead
3. Pin a ray version compatible with your sglang release

Example fix

# before: ImportError raised
metric = RayPrometheusMetric()
# after
# shell: pip install 'ray[serve]'
metric = RayPrometheusMetric()

try:
    import ray.metrics  # or ray.serve
    ray_ok = True
except ImportError:
    ray_ok = False
metric_cls = RayPrometheusMetric if ray_ok else StandardPrometheusMetric

try:
    m = RayPrometheusMetric()
except ImportError:
    m = StandardPrometheusMetric()  # fallback wrapper

When it happens

Trigger: Instantiating RayPrometheusMetric in an environment where `import ray` (or its metrics module) failed — plain sglang install without ray.

Common situations: Deploying sglang with the ray observability path enabled (e.g. ray serve integration) but ray not in the image; slim Docker images; CI environments trimming optional deps.

Related errors

• Number of labels must match the number of tag keys. Expected
• labels() cannot be called on an already-labeled metric.
• opentelemetry package is not installed!!! Please not enable
• Cannot find NVIDIA Math-DX (cuBLASDx) headers. Install the `
• Cannot find CUTLASS headers required for JIT compilation. Pl

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