BerriAI/litellm · error · ImportError

OpenTelemetry OTLP gRPC metric exporter is not available…

Error message

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

What it means

In the OTel v2 plumbing (litellm/integrations/otel), when the metric exporter kind is otlp_grpc or grpc the provider builder lazily imports OTLPMetricExporter from opentelemetry.exporter.otlp.proto.grpc.metric_exporter; if the opentelemetry-exporter-otlp distribution or grpcio is missing, the ImportError is re-raised with instructions (including the litellm[grpc] extra) chained to the original failure. This is the v2-path twin of the same check in the classic opentelemetry.py callback.

Solutions

Install the dependencies in the runtime environment: pip install 'litellm[grpc]' or pip install opentelemetry-exporter-otlp grpcio
Or configure the v2 exporter kind as otlp_http/http/protobuf to use the collector's HTTP port with no grpcio requirement
Verify inside the deployed image: python -c "from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import OTLPMetricExporter"
Rebuild/restart so the provider constructs cleanly

Example fix

# before
# v2 config exporter: otlp_grpc; runtime deps: litellm only -> ImportError
# after
pip install 'litellm[grpc]'

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util

if config.exporter in ('otlp_grpc', 'grpc'):  # v2 OpenTelemetryV2Config exporter kind
    if importlib.util.find_spec('opentelemetry.exporter.otlp.proto.grpc.metric_exporter') is None:
        raise SystemExit('v2 gRPC metrics require: pip install opentelemetry-exporter-otlp grpcio (or litellm[grpc])')

Try / catch

try:
    from litellm.integrations.otel.plumbing.providers import build_meter_provider
    reader = build_meter_provider(config)
except ImportError as e:
    if 'litellm[grpc]' in str(e):
        raise SystemExit("pip install 'litellm[grpc]' or set exporter kind to otlp_http") from e
    raise

Prevention

When adopting the v2 OTel integration, extend the image deps in the same change as the exporter kind
Share one preflight across v1/v2 paths — the gRPC requirement is identical
Prefer otlp_http on slim/alpine images unless 4317 gRPC is mandated by your collector setup
Add a build-time import check for every exporter module referenced by config

When it happens

Trigger: Configuring OpenTelemetry v2 with exporter kind otlp_grpc/grpc and metrics enabled, in a runtime lacking the gRPC OTLP packages — slim containers, pruned lockfiles, or fresh venvs with bare litellm. Raised while building the metric reader (PeriodicExportingMetricReader) during callback/provider setup.

Common situations: Adopting the v2 OTel integration on an image that only ever shipped HTTP exporters; grpcio removed from requirements for image-size reasons; mixed installs where opentelemetry SDK upgrades dropped or renamed extras; local dev working (package present transitively) while CI/deploy fails.

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/c6bde5b8de362e3d. Report an issue: GitHub.

Appendix: source

Thrown at litellm/integrations/otel/plumbing/providers.py:239

    )

    kind: Final = (config.exporter or "console").lower()
    if kind in ("otlp_http", "http", "http/protobuf", "http/json"):
        from opentelemetry.exporter.otlp.proto.http.metric_exporter import (
            OTLPMetricExporter as HTTPMetricExporter,
        )

        exporter: Any = HTTPMetricExporter(
            endpoint=_otlp_metrics_endpoint(config.endpoint),
            headers=parse_headers(config.headers),
        )
    elif kind in ("otlp_grpc", "grpc"):
        try:
            from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import (
                OTLPMetricExporter as GRPCMetricExporter,
            )
        except ImportError as exc:
            raise ImportError(
                "OpenTelemetry OTLP gRPC metric exporter is not available. Install "
                "`opentelemetry-exporter-otlp` and `grpcio` (or `litellm[grpc]`)."
            ) from exc

        exporter = GRPCMetricExporter(
            endpoint=config.endpoint,
            headers=parse_headers(config.headers),
        )
    else:
        exporter = ConsoleMetricExporter()

    return PeriodicExportingMetricReader(exporter, export_interval_millis=5000)


def _otlp_logs_endpoint(endpoint: str | None) -> str | None:
    """Point an OTLP/HTTP base endpoint at the ``/v1/logs`` signal path.

    The OTLP/HTTP exporter only appends ``/v1/logs`` when it reads

View on GitHub (pinned to 77b7c6c40c)