Skip to content

OpenTelemetry Exporter Connection Refused Fix

DodaTech Updated 2026-06-24 3 min read

In this tutorial, you'll learn about OpenTelemetry Exporter Connection Refused Fix. We cover key concepts, practical examples, and best practices.

Your OpenTelemetry SDK logs Failed to export spans. Connection refused — the OTLP exporter cannot reach the OpenTelemetry Collector or backend. The endpoint URL is wrong, TLS is misconfigured, or nothing is listening on the target port.

The Problem

# WRONG — using HTTPS instead of HTTP for the local collector
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter

exporter = OTLPSpanExporter(
    endpoint="https://localhost:4317",
    insecure=False
)
ERROR: Failed to export spans. Connection refused
Status: StatusCode.UNAVAILABLE

The collector runs insecurely on HTTP port 4317, but the exporter tries HTTPS. With insecure=False, the gRPC client attempts TLS handshake, which the non-TLS collector rejects.

Step-by-Step Fix

1. Match the protocol to the collector

# For gRPC with TLS (collector with TLS)
exporter = OTLPSpanExporter(
    endpoint="https://collector.example.com:4317",
    insecure=False
)

# For gRPC without TLS (local collector)
exporter = OTLPSpanExporter(
    endpoint="http://localhost:4317",
    insecure=True
)

# For HTTP/protobuf
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

exporter = OTLPSpanExporter(
    endpoint="http://localhost:4318/v1/traces"
)

2. Verify the collector is running

# Check if the collector is listening
netstat -tlnp | grep 4317

# If using Docker
docker ps | grep otel-collector

# Test gRPC connectivity
grpcurl -plaintext localhost:4317 list

3. Configure the collector properly

# otel-collector-config.yaml
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

exporters:
  otlp:
    endpoint: jaeger:4317
  logging:
    loglevel: debug

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [otlp, logging]

4. Set environment variables for the SDK

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_INSECURE=true
export OTEL_SERVICE_NAME=myapp

5. Handle TLS certificates

# Custom TLS certificate
exporter = OTLPSpanExporter(
    endpoint="https://collector.example.com:4317",
    credentials=grpc.ssl_channel_credentials(
        root_certificates=open('/path/to/ca.crt', 'rb').read()
    )
)

Expected output:

OpenTelemetry Collector: localhost:4317
Connection: OK
Exported: 15 spans, 20 metrics, 3 logs
✓ Telemetry pipeline healthy

Prevention Tips

  • Use environment variables (OTEL_EXPORTER_OTLP_ENDPOINT) for endpoint configuration
  • Verify collector port with netstat or docker ps
  • Match insecure setting to collector's TLS configuration
  • Use collector health check: curl http://localhost:13133/health
  • Add otlp exporter logging for debugging

Common Mistakes with exporter

  1. Misunderstanding that String is [Char] with poor performance for large text operations
  2. Using foldl instead of foldl' causing stack overflow on large lists
  3. Forgetting deriving (Show, Eq) on custom data types needed for debugging

These mistakes appear frequently in real-world OPENTELEMETRY code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ

### What's the difference between OTLP gRPC (4317) and OTLP HTTP (4318)?

gRPC (port 4317) uses binary protobuf encoding — faster and more efficient, but requires gRPC support. HTTP (port 4318) uses JSON or protobuf over HTTP — easier to debug with curl, works with HTTP proxies. Use gRPC for production, HTTP for debugging.

How do I send telemetry to multiple backends?

Configure the OpenTelemetry Collector with multiple exporters: otlp (to another backend), <a href="/devops/prometheus-grafana/">prometheus</a>, loki, zipkin. Use the batch processor and set exporters in the pipeline. The application sends to the collector, the collector fans out to backends.

Why does the exporter work locally but not in Docker/Kubernetes?

In Docker, use the service name or container name as host. In Kubernetes, use the collector Service DNS name (e.g., otel-collector.observability.svc.cluster.local). Set OTEL_EXPORTER_OTLP_INSECURE=true for internal cluster communication without TLS.

Built by the developers of DodaTech

Doda Browser, DodaZIP & Durga Antivirus Pro