otelcol "failed to load config" in CI

By Daniel Zoghalchali·Latchkey

The OpenTelemetry Collector validates its config on startup; when a key is unknown, a referenced component is not defined, or a pipeline lists a missing receiver/exporter, it exits with "failed to load config" and a precise reason.

What this error means

otelcol (or otelcol-contrib) exits non-zero at startup with "Error: failed to load config" and a message like "error decoding ... cannot unmarshal" or "references ... which is not configured".

Error: failed to get config: cannot unmarshal the configuration: 1 error(s) decoding:
* error decoding 'service.pipelines.traces.exporters': references exporter "otlp/backend" which is not defined

Common causes

A pipeline references an undefined component

A pipeline lists a receiver, processor, or exporter id that is not defined in the corresponding top-level section, so the config is invalid.

An unknown key or wrong indentation

A misspelled field or a misplaced block fails strict decoding, and the collector refuses to start.

How to fix it

Define every component the pipeline uses

1. Read which component id the error says is not defined.
2. Add it under the matching receivers/processors/exporters section.
3. Re-run; validate the config before deploy.

exporters:
  otlp/backend:
    endpoint: collector.example.com:4317
service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [otlp/backend]

Validate the config in CI

Run the collector validate subcommand as a gate so a broken config fails fast.

otelcol validate --config otelcol.yaml

How to prevent it

• Validate collector config with otelcol validate in CI.
• Keep pipeline component ids in sync with their definitions.
• Use the contrib distro only when a component requires it.

Frequently asked questions

Related guides

References

• GitHub Actions documentation