🚨 OpenTelemetry Error Guide: 'failed to parse config' — Fix Collector Startup

Overview

This error stops the OpenTelemetry Collector before it processes any telemetry: the configuration file could not be loaded or validated, so the process exits non-zero at startup:

Error: failed to get config: cannot unmarshal the configuration: 1 error(s) decoding:

* error decoding 'exporters': unknown type: "otlphttp/backend" for id: "otlphttp/backend" (valid values: [debug otlp otlphttp file nop])
2026/07/09 07:14:55 collector server run finished with error: failed to get config

Other common variants include yaml: line 22: mapping values are not allowed in this context, unknown type for a receiver/processor/exporter, and references processor "batch" which is not configured. All mean the Collector never started.

Symptoms

• The Collector container exits immediately or enters CrashLoopBackOff.
• Logs show failed to get config, cannot unmarshal the configuration, or a yaml: parse error.
• A named component is reported as unknown type or is not configured.
• No telemetry flows because the process never reached the running state.
• kubectl describe pod shows the container terminating with a non-zero exit code.

Common Root Causes

• YAML indentation errors — tabs, misaligned keys, or a value where a mapping is expected.
• Unknown component type — a receiver/processor/exporter type not built into your Collector distribution.
• Component defined but not wired — a component under processors: that is missing from a service.pipelines list (or vice-versa).
• Distribution mismatch — using a contrib-only component in the core otelcol binary.
• Env var not expanded — ${ENV} unset, so the value is empty or malformed.
• Wrong config path — --config points at a missing or stale file.

Diagnostic Workflow

Validate the config without starting the pipelines. The Collector’s validate subcommand reports the exact decoding error:

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

Every component you define must be referenced in service, and every reference must be defined. A correct minimal config looks like this:

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

processors:
  batch:
    timeout: 5s

exporters:
  otlphttp:
    endpoint: ${env:BACKEND_OTLP_ENDPOINT}

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]      # 'batch' must be defined above
      exporters: [otlphttp]    # 'otlphttp' must be defined above

Confirm the environment variables the config references are actually set for the process:

echo "$BACKEND_OTLP_ENDPOINT"
tr '\0' '\n' < /proc/$(pgrep -f otelcol)/environ | grep BACKEND_OTLP_ENDPOINT

Read the exact parse failure and line number from the startup logs:

journalctl -u otelcol-contrib --since '5 min ago' | grep -iE 'failed to get config|cannot unmarshal|unknown type|yaml:'

Example Root Cause Analysis

An engineer added otlphttp/backend as an exporter id but the deployment ran the core otelcol image, which does not include every contrib exporter. On startup the Collector reported unknown type: "otlphttp/backend" (the type before the / is what matters — here the type was fine, but a similar edit had introduced a spanmetrics connector unavailable in core). The pod crash-looped and no traces flowed.

Root-causing was fast with otelcol validate --config, which printed the exact offending id and the list of valid types for that section. The fix was to switch the image to otel/opentelemetry-collector-contrib, which bundles the required components. As a guardrail, otelcol validate was added to CI so a config referencing a component absent from the target distribution fails the pipeline instead of crash-looping in production.

Prevention Best Practices

• Run otelcol validate --config <file> in CI so bad YAML or unknown components fail before deploy.
• Match your config to your distribution: use -contrib when you need contrib components.
• Keep indentation consistent (spaces, never tabs); lint with a YAML linter in CI.
• Ensure every component is both defined and referenced in service.pipelines; remove orphans.
• Use ${env:VAR} expansion with defaults where possible and verify the vars are set in the runtime.
• Pin the Collector image version so a component available today is not removed by an upgrade unnoticed.

Quick Command Reference

# Validate config without running
otelcol-contrib validate --config /etc/otelcol/config.yaml

# Lint YAML syntax
yamllint /etc/otelcol/config.yaml

# Read the exact parse error
journalctl -u otelcol-contrib | grep -iE 'unmarshal|unknown type|yaml:'

# Confirm referenced env vars are set
tr '\0' '\n' < /proc/$(pgrep -f otelcol)/environ | grep -E 'BACKEND|OTLP'

Conclusion

failed to parse config is a fail-fast guard: the Collector refuses to run rather than start with a broken pipeline. The error text names the exact problem — a YAML line, an unknown type, or an unwired component — so read it, then validate with otelcol validate --config and match the config to your distribution. Wiring that check into CI turns a production crash-loop into a caught build failure, which is exactly where a config error should surface.