{"record":{"id":"4323f1ff078821c3","repo":"BerriAI/litellm","slug":"opentelemetry-otlp-grpc-exporter-is-not-available","errorCode":null,"errorMessage":"OpenTelemetry OTLP gRPC exporter is not available. Install `opentelemetry-exporter-otlp` and `grpcio` (or `litellm[grpc]`).","messagePattern":"OpenTelemetry OTLP gRPC exporter is not available\\. Install `opentelemetry-exporter-otlp` and `grpcio` \\(or `litellm\\[grpc\\]`\\)\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"litellm/integrations/opentelemetry.py","lineNumber":2908,"sourceCode":"                    \"OpenTelemetry OTLP HTTP exporter is not available. Install \"\n                    \"`opentelemetry-exporter-otlp` to enable OTLP HTTP.\"\n                ) from exc\n\n            verbose_logger.debug(\n                \"OpenTelemetry: intiializing http exporter. Value of OTEL_EXPORTER: %s\",\n                otel_exporter,\n            )\n            normalized_endpoint = self._normalize_otel_endpoint(otel_endpoint, \"traces\")\n            return BatchSpanProcessor(\n                OTLPSpanExporterHTTP(endpoint=normalized_endpoint, headers=_split_otel_headers),\n            )\n        elif otel_exporter == \"otlp_grpc\" or otel_exporter == \"grpc\":\n            try:\n                from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (\n                    OTLPSpanExporter as OTLPSpanExporterGRPC,\n                )\n            except ImportError as exc:\n                raise ImportError(\n                    \"OpenTelemetry OTLP gRPC exporter is not available. Install \"\n                    \"`opentelemetry-exporter-otlp` and `grpcio` (or `litellm[grpc]`).\"\n                ) from exc\n\n            verbose_logger.debug(\n                \"OpenTelemetry: intiializing grpc exporter. Value of OTEL_EXPORTER: %s\",\n                otel_exporter,\n            )\n            normalized_endpoint = self._normalize_otel_endpoint(otel_endpoint, \"traces\")\n            return BatchSpanProcessor(\n                OTLPSpanExporterGRPC(endpoint=normalized_endpoint, headers=_split_otel_headers),\n            )\n        else:\n            verbose_logger.debug(\n                \"OpenTelemetry: intiializing console exporter. Value of OTEL_EXPORTER: %s\",\n                otel_exporter,\n            )\n            return BatchSpanProcessor(ConsoleSpanExporter())","sourceCodeStart":2890,"sourceCodeEnd":2926,"githubUrl":"https://github.com/BerriAI/litellm/blob/77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8/litellm/integrations/opentelemetry.py#L2890-L2926","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before\n# OTEL_EXPORTER=otlp_grpc, deps: pip install litellm\n# -> ImportError at span exporter init\n\n# after\npip install 'litellm[grpc]'\n# or: pip install opentelemetry-exporter-otlp grpcio","handlingStrategy":"validation","validationCode":"import importlib.util, os\n\nif os.getenv('OTEL_EXPORTER') in ('otlp_grpc', 'grpc'):\n    missing = [m for m in ('opentelemetry.exporter.otlp.proto.grpc.trace_exporter', 'grpc') if importlib.util.find_spec(m) is None]\n    if missing:\n        raise SystemExit(f'gRPC exporter requires opentelemetry-exporter-otlp + grpcio (or litellm[grpc]); missing: {missing}')","typeGuard":null,"tryCatchPattern":"try:\n    cb = OpenTelemetry()\nexcept ImportError as e:\n    if 'litellm[grpc]' in str(e):\n        raise SystemExit(\"pip install 'litellm[grpc]' or switch to OTEL_EXPORTER=otlp_http\") from e\n    raise","preventionTips":["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"],"tags":["opentelemetry","otel","import-error","missing-dependency","otlp-grpc","grpcio","packaging"],"backgroundTag":"missing-optional-dependency","analyzedSha":"77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8","analyzedAt":"2026-08-18T11:44:31.656Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}