OpenTelemetry JS "OTLPExporterError ECONNREFUSED" (port 4317/4318) in CI

Your app initialized an OTLP exporter that pushes spans to a collector on localhost:4317 (gRPC) or 4318 (HTTP), but no collector runs in the CI job, so every export fails with ECONNREFUSED. The traces are noise; the tests should not depend on a collector.

What this error means

Tests log repeated "OTLPExporterError: 14 UNAVAILABLE" or "connect ECONNREFUSED 127.0.0.1:4317" from the exporter while the collector is absent. The suite may still pass but the log is flooded, or a shutdown hangs waiting to flush.

OTLPExporterError: connect ECONNREFUSED 127.0.0.1:4318
    at ClientRequest.<anonymous> (node_modules/@opentelemetry/otlp-exporter-base/...)
    code: 'ECONNREFUSED', address: '127.0.0.1', port: 4318

Common causes

No collector listens on 4317/4318 in CI

The default OTLP endpoint is http://localhost:4317 (gRPC) or http://localhost:4318 (HTTP). Locally a collector or agent runs; in the CI job nothing is bound to that port, so the TCP connect is refused.

Instrumentation is initialized unconditionally in tests

The tracer SDK and OTLP exporter are set up at import time regardless of environment, so importing the app under test starts exporting to a dead endpoint.

How to fix it

Disable real export during tests

1. Set the OTel SDK to a no-op or in-memory exporter when running tests.
2. The official env var OTEL_SDK_DISABLED=true turns the SDK off entirely.
3. Alternatively swap the exporter for InMemorySpanExporter in test setup.

env:
  OTEL_SDK_DISABLED: 'true'   # no exporter starts, no ECONNREFUSED

Run a collector as a service if you must export

When a test genuinely asserts on exported spans, start a collector as a job service and point the endpoint at it.

services:
  otelcol:
    image: otel/opentelemetry-collector:latest
    ports: ['4317:4317', '4318:4318']

How to prevent it

• Gate SDK/exporter setup behind an environment check so tests do not export.
• Prefer InMemorySpanExporter for assertions instead of a live collector.
• Set OTEL_SDK_DISABLED=true for unit test jobs.

Related guides