🚨 OpenTelemetry Error Guide: 'references exporter which is not configured' — Fix Collector Pipeline Wiring

Overview

The Collector validates that every component named in a service::pipelines block is actually defined in the top-level receivers, processors, or exporters sections. When a pipeline references a component ID that isn’t defined, the Collector refuses to start:

Error: invalid configuration: service::pipelines::traces: references exporter "otlp/backend" which is not configured

The same class of error appears for processors and receivers:

Error: invalid configuration: service::pipelines::metrics: references processor "batch/metrics" which is not configured

This is a fail-fast startup error — the Collector will not run until the reference is resolved, so no telemetry flows.

Symptoms

• The Collector crashes immediately on start or reload with references ... which is not configured.
• The failing component ID is named in the error (e.g. otlp/backend, batch/metrics).
• Started after editing pipelines, renaming a named-instance component, or merging config fragments.
• otelcol validate fails; the pod enters CrashLoopBackOff.
• A component is defined but under a different name or a mismatched named instance.

Common Root Causes

• Typo in the pipeline reference — the ID in pipelines doesn’t exactly match the defined key.
• Named-instance mismatch — defined as otlp/backend but referenced as otlp/prod (the part after / is part of the ID).
• Component defined in the wrong section — an exporter listed under processors, or vice versa.
• Deleted/renamed component — the definition was removed or renamed but a pipeline still references the old ID.
• Merged/overlay config drift — a base and overlay file disagree on component names.
• Wrong indentation — a component nested one level off so it isn’t registered where expected.

Diagnostic Workflow

Read the error carefully: it names the pipeline (service::pipelines::traces), the component kind (exporter), and the exact ID (otlp/backend). Every referenced ID must appear verbatim as a key in the matching top-level section:

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

processors:
  batch: {}

exporters:
  otlp/backend:                 # <- the ID that must match the pipeline reference
    endpoint: otel-backend:4317
    tls:
      insecure: true

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp/backend]  # must match the key above exactly, including "/backend"

Validate before deploying so the failure is caught locally, not in a crash loop:

otelcol validate --config /etc/otelcol/config.yaml

For Kubernetes, inspect the rendered config and the crash logs:

kubectl -n observability logs deploy/otel-collector --previous | grep -i 'not configured'
kubectl -n observability get cm otel-collector-config -o yaml | grep -A3 'exporters:'

Example Root Cause Analysis

An engineer renamed the production exporter from otlp to otlp/backend to add a second otlp/dev instance, updating the exporters section but forgetting the traces pipeline, which still listed exporters: [otlp]. On reload the Collector logged service::pipelines::traces: references exporter "otlp" which is not configured and entered CrashLoopBackOff, taking the whole gateway down.

otelcol validate reproduced the error instantly and named the stale reference. Updating the traces pipeline to exporters: [otlp/backend] resolved it. The team then added otelcol validate as a pre-deploy CI gate so a mismatched component ID could never reach the cluster again.

Prevention Best Practices

• Run otelcol validate --config in CI on every change so reference mismatches fail the pipeline, not the Collector.
• Treat the full component ID — including the /instance suffix — as one atomic name; rename it in both the definition and every pipeline reference together.
• Keep receivers, processors, and exporters in their correct top-level sections; the Collector matches by kind and ID.
• When using base/overlay config, diff the merged result and validate that, not just the fragments.
• Roll out Collector config changes to a canary first so a bad reference doesn’t crash the whole fleet.

Quick Command Reference

# Fail-fast validation before deploy
otelcol validate --config /etc/otelcol/config.yaml

# See the exact stale reference from a crash
kubectl -n observability logs deploy/otel-collector --previous | grep -i 'not configured'

# Inspect the rendered ConfigMap
kubectl -n observability get cm otel-collector-config -o yaml

# List defined exporter IDs quickly
grep -A1 'exporters:' /etc/otelcol/config.yaml

Conclusion

references exporter which is not configured is a wiring error: a service::pipelines block names a component ID that doesn’t exist in the matching top-level section. Match the IDs exactly — instance suffix included — keep components in their correct sections, and gate every change with otelcol validate. Validating in CI turns a fleet-wide crash loop into a caught typo.