BerriAI/litellm · error · ImportError

OpenTelemetry OTLP gRPC exporter is not available. Install…

Error message

OpenTelemetry OTLP gRPC exporter is not available. Install `opentelemetry-exporter-otlp` and `grpcio` (or `litellm[grpc]`).

What it means

With exporter set to otlp_grpc (or grpc), the callback lazily imports the OTLP gRPC span exporter from opentelemetry.exporter.otlp.proto.grpc.trace_exporter. gRPC support requires both the opentelemetry-exporter-otlp distribution and the grpcio package (itself heavy and optional — litellm exposes it as the litellm[grpc] extra). A missing either one surfaces as ImportError re-raised with install instructions, chaining the original ImportError.

Solutions

Install both packages: pip install opentelemetry-exporter-otlp grpcio — or the bundled extra: pip install 'litellm[grpc]'
If you did not intend gRPC, switch the protocol to HTTP: OTEL_EXPORTER=otlp_http (collector port 4318) which needs only opentelemetry-exporter-otlp
On alpine/slim bases, prefer a manylinux-compatible base or prebuilt wheels to avoid grpcio build failures
Rebuild the image and restart the proxy/SDK process

Example fix

# before
# OTEL_EXPORTER=otlp_grpc, deps: pip install litellm
# -> ImportError at span exporter init

# after
pip install 'litellm[grpc]'
# or: pip install opentelemetry-exporter-otlp grpcio

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util, os

if os.getenv('OTEL_EXPORTER') in ('otlp_grpc', 'grpc'):
    missing = [m for m in ('opentelemetry.exporter.otlp.proto.grpc.trace_exporter', 'grpc') if importlib.util.find_spec(m) is None]
    if missing:
        raise SystemExit(f'gRPC exporter requires opentelemetry-exporter-otlp + grpcio (or litellm[grpc]); missing: {missing}')

Try / catch

try:
    cb = OpenTelemetry()
except ImportError as e:
    if 'litellm[grpc]' in str(e):
        raise SystemExit("pip install 'litellm[grpc]' or switch to OTEL_EXPORTER=otlp_http") from e
    raise

Prevention

Add 'litellm[grpc]' to requirements in the same commit that switches OTEL_EXPORTER to otlp_grpc
On alpine/slim bases, verify grpcio installs (prefer manylinux images) before relying on gRPC export
Run a build-time import check for the gRPC exporter module in your Dockerfile
Track collector port choice (4317 grpc vs 4318 http) together with the dependency choice

When it happens

Trigger: Setting OTEL_EXPORTER=otlp_grpc / OTEL_EXPORTER_OTLP_PROTOCOL=grpc and enabling the otel callback where opentelemetry-exporter-otlp or grpcio is not installed. Common on slim/alpine images (grpcio wheels are platform-sensitive), Apple Silicon vs linux wheel mismatches, and venvs where only the HTTP exporter was ever installed.

Common situations: Teams migrating from OTLP HTTP to gRPC (e.g. pointing at a collector's 4317 port) without adding the new dependency; alpine/slim base images where grpcio must compile or is absent; multi-stage Docker builds that prune 'unused' packages; pip install litellm[proxy] which does not include the grpc extra.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

AI-assisted analysis of BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/4323f1ff078821c3. Report an issue: GitHub.

Appendix: source

Thrown at litellm/integrations/opentelemetry.py:2908

                    "OpenTelemetry OTLP HTTP exporter is not available. Install "
                    "`opentelemetry-exporter-otlp` to enable OTLP HTTP."
                ) from exc

            verbose_logger.debug(
                "OpenTelemetry: intiializing http exporter. Value of OTEL_EXPORTER: %s",
                otel_exporter,
            )
            normalized_endpoint = self._normalize_otel_endpoint(otel_endpoint, "traces")
            return BatchSpanProcessor(
                OTLPSpanExporterHTTP(endpoint=normalized_endpoint, headers=_split_otel_headers),
            )
        elif otel_exporter == "otlp_grpc" or otel_exporter == "grpc":
            try:
                from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
                    OTLPSpanExporter as OTLPSpanExporterGRPC,
                )
            except ImportError as exc:
                raise ImportError(
                    "OpenTelemetry OTLP gRPC exporter is not available. Install "
                    "`opentelemetry-exporter-otlp` and `grpcio` (or `litellm[grpc]`)."
                ) from exc

            verbose_logger.debug(
                "OpenTelemetry: intiializing grpc exporter. Value of OTEL_EXPORTER: %s",
                otel_exporter,
            )
            normalized_endpoint = self._normalize_otel_endpoint(otel_endpoint, "traces")
            return BatchSpanProcessor(
                OTLPSpanExporterGRPC(endpoint=normalized_endpoint, headers=_split_otel_headers),
            )
        else:
            verbose_logger.debug(
                "OpenTelemetry: intiializing console exporter. Value of OTEL_EXPORTER: %s",
                otel_exporter,
            )
            return BatchSpanProcessor(ConsoleSpanExporter())

View on GitHub (pinned to 77b7c6c40c)