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

Overview

Every component named inside a service::pipelines block must also be defined in the corresponding top-level block. When a pipeline lists a processor ID that has no matching entry under processors:, the Collector fails validation at startup and names the missing ID:

Error: failed to build pipelines: service::pipelines::traces: references processor "batch/2" which is not configured
2026/07/12 09:41:03 collector server run finished with error: invalid configuration

The same class of error appears for other signals and component kinds, for example:

Error: failed to build pipelines: service::pipelines::metrics: references processor "memory_limiter" which is not configured

The message means the pipeline points at a processor instance (here batch/2) that is not declared in the top-level processors: map — almost always a typo, a wrong named-component suffix, or a processor that was removed but still referenced.

Symptoms

• The Collector refuses to start and logs references processor "<id>" which is not configured.
• The error names a specific pipeline (traces, metrics, or logs) and a specific processor ID.
• A component ID in the pipeline list has a suffix (batch/2) that does not exist under processors:.
• The config passed validation before a recent edit that renamed or removed a processor.
• Only one signal pipeline fails while others with correctly wired processors start fine.
• otelcol-contrib validate reports the same missing-reference message.

Common Root Causes

• Typo in the pipeline reference — the pipeline lists batch/2 but the block defines batch or batch/two.
• Named-component suffix mismatch — processors use type/name IDs; the name after the slash must match exactly (batch/2 ≠ batch).
• Processor removed but still referenced — a top-level entry was deleted while the pipeline list still names it.
• Wrong block — the component was defined under extensions: or as an exporter, not under processors:.
• Case or whitespace drift — an invisible trailing space or different casing makes two IDs that look identical fail to match.
• Copy-paste across pipelines — a logs pipeline inherits a processor ID that only exists for traces.

Diagnostic Workflow

Start by validating the config so the Collector names the exact missing ID and pipeline:

otelcol-contrib validate --config /etc/otelcol-contrib/config.yaml
journalctl -u otelcol-contrib --since '10 min ago' | grep -i 'not configured'

Now line up the two places the ID must appear. Every entry in a pipeline’s processors: list must be a key under the top-level processors: map. In this broken config the pipeline names batch/2, but only batch is defined:

processors:
  batch:                     # defined
    send_batch_size: 512
  memory_limiter:
    check_interval: 1s
    limit_mib: 512

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, batch/2]   # WRONG: batch/2 is undefined
      exporters: [otlp]

Fix it by making the reference match a defined ID. Either correct the pipeline reference, or add the named instance to the top-level block. Correcting the reference:

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, batch]     # matches the defined key
      exporters: [otlp]

If you genuinely want a second batch instance, define it as a named component and then reference it:

processors:
  batch:
    send_batch_size: 512
  batch/2:                   # named instance, now it exists
    send_batch_size: 8192
    timeout: 10s

List the defined processor IDs quickly to compare against the pipeline lists:

# Print the keys under the top-level processors: block
otelcol-contrib validate --config /etc/otelcol-contrib/config.yaml && \
  grep -nE '^\s{2}[a-z].*:' /etc/otelcol-contrib/config.yaml

Example Root Cause Analysis

An engineer split a single batch processor into two — a fast small batch for traces and a large batch for metrics — and added batch/2 to the metrics pipeline. During a rushed edit they also added batch/2 to the traces pipeline but forgot to define the batch/2 key under the top-level processors: block. The Collector failed to build pipelines with service::pipelines::traces: references processor "batch/2" which is not configured, and the whole agent stayed down, taking traces and metrics with it.

The fix had two parts. First, the top-level processors: block gained a real batch/2: entry with its intended send_batch_size and timeout, so the reference resolved. Second, a pre-deploy otelcol-contrib validate gate was added to the deployment pipeline; because validation walks every service::pipelines::* reference against the defined components, the missing ID would have failed CI instead of crashing the running Collector. After both changes the agent started cleanly and every pipeline referenced only defined processors.

Prevention Best Practices

• Treat pipeline processors: lists as pointers — every entry must be a key in the top-level processors: map, suffix and all.
• Run otelcol-contrib validate in CI so a dangling reference fails the pull request, not the pod.
• Keep named-component IDs (type/name) consistent; decide on a naming convention and stick to it.
• When removing a processor, grep every pipeline for its ID before deleting the definition.
• Avoid copy-pasting pipeline blocks between signals without re-checking each referenced component exists.
• Lint for trailing whitespace and casing so two IDs that should match actually do.

Quick Command Reference

# Validate config and reveal the missing processor reference
otelcol-contrib validate --config /etc/otelcol-contrib/config.yaml

# Watch the startup failure
journalctl -u otelcol-contrib --since '10 min ago' | grep -i 'not configured'

# Find every place an ID is referenced before deleting its definition
grep -n 'batch/2' /etc/otelcol-contrib/config.yaml

# Restart after fixing the wiring
systemctl restart otelcol-contrib

Conclusion

references processor which is not configured is a wiring error: a pipeline points at a processor ID that has no matching definition under the top-level processors: block. Read the exact ID and pipeline from the message, then either correct the reference to a defined key or add the named instance you intended. Because Collector validation resolves every pipeline reference, gating deploys on otelcol-contrib validate catches this before it ever takes an agent offline.

Related

• OpenTelemetry Error Guide: ‘references exporter which is not configured’
• OpenTelemetry Error Guide: ‘failed to parse config’
• OpenTelemetry Error Guide: ‘address already in use’