vllm-project/vllm · error · ValueError

OpenTelemetry is not available. Unable to configure 'otlp_tr

Error message

OpenTelemetry is not available. Unable to configure 'otlp_traces_endpoint'. Ensure OpenTelemetry packages are installed. Original error:
{otel_import_error_traceback}

What it means

ObservabilityConfig's field validator for otlp_traces_endpoint imports vllm.tracing helpers and checks is_tracing_available(). If the OpenTelemetry packages could not be imported, setting --otlp-traces-endpoint is rejected with the original import traceback appended, because OTLP export cannot function without them.

Source

Thrown at vllm/config/observability.py:135

        hash_str = safe_hash(str(factors).encode(), usedforsecurity=False).hexdigest()
        return hash_str

    @field_validator("show_hidden_metrics_for_version")
    @classmethod
    def _validate_show_hidden_metrics_for_version(cls, value: str | None) -> str | None:
        if value is not None:
            # Raises an exception if the string is not a valid version.
            parse(value)
        return value

    @field_validator("otlp_traces_endpoint")
    @classmethod
    def _validate_otlp_traces_endpoint(cls, value: str | None) -> str | None:
        if value is not None:
            from vllm.tracing import is_tracing_available, otel_import_error_traceback

            if not is_tracing_available():
                raise ValueError(
                    "OpenTelemetry is not available. Unable to configure "
                    "'otlp_traces_endpoint'. Ensure OpenTelemetry packages are "
                    f"installed. Original error:\n{otel_import_error_traceback}"
                )
        return value

    @field_validator("collect_detailed_traces")
    @classmethod
    def _validate_collect_detailed_traces(
        cls, value: list[DetailedTraceModules] | None
    ) -> list[DetailedTraceModules] | None:
        """Handle the legacy case where users might provide a comma-separated
        string instead of a list of strings."""
        if value is not None and len(value) == 1 and "," in value[0]:
            value = cast(list[DetailedTraceModules], value[0].split(","))
        return value

    @model_validator(mode="after")

View on GitHub (pinned to c794754062)

Solutions

Install the OTel extras, e.g. uv pip install -r requirements/observability.txt or opentelemetry-sdk opentelemetry-exporter-otlp (match the versions vllm.tracing imports).
Re-check with python -c "from vllm.tracing import is_tracing_available; print(is_tracing_available())" — the traceback field of this error tells you exactly which import failed.
If tracing is optional in your deployment, drop --otlp-traces-endpoint until the packages are present.

Example fix

# before
vllm serve model --otlp-traces-endpoint http://otel:4317  # otel not installed -> ValueError

# after
uv pip install opentelemetry-sdk opentelemetry-exporter-otlp
vllm serve model --otlp-traces-endpoint http://otel:4317

Defensive patterns

Strategy: validation

Validate before calling

from vllm.tracing import is_tracing_available

def require_otel(endpoint: str | None) -> None:
    if endpoint and not is_tracing_available():
        raise SystemExit("Install opentelemetry-sdk + opentelemetry-exporter-otlp before enabling OTLP")

Type guard

def tracing_ready() -> bool:
    try:
        from vllm.tracing import is_tracing_available
        return is_tracing_available()
    except Exception:
        return False

Prevention

Bake OTel packages into serving images whenever the endpoint flag is templated in.
Smoke-test the import (python -c 'from vllm.tracing import is_tracing_available; assert is_tracing_available()') in CI.

When it happens

Trigger: Passing --otlp-traces-endpoint http://collector:4317 in an environment where vllm.tracing's OTel import failed — e.g. opentelemetry-sdk / opentelemetry-exporter-otlp not installed, or an incompatible/broken OTel version on sys.path.

Common situations: Minimal docker images or slim venvs that omit the optional tracing extras; upgrading vLLM without reinstalling otel packages; a half-broken OTel install where a submodule import raises.

Related errors

AI-assisted analysis of vllm-project/vllm@c794754062 (2026-08-14). Data as JSON: /api/errors/3c2771c621a3880a. Report an issue: GitHub.