otelcol validate: Check Collector Config in CI
otelcol validate --config <file> parses and validates a Collector configuration, exiting non-zero on errors so a broken pipeline config fails CI.
The OpenTelemetry Collector refuses to start on a bad config. otelcol validate runs that same parsing in CI so you catch an unknown component or a missing required field before deploy.
What it does
otelcol validate loads the config, builds the receiver/processor/exporter pipelines, and checks that every referenced component exists and its settings are valid, then exits without running the collector. The distribution matters: components live in otelcol-contrib, not the core otelcol binary.
Common usage
otelcol validate --config=otel-collector-config.yaml
# the contrib distribution (more components)
otelcol-contrib validate --config=config.yaml
# merge multiple config files
otelcol validate --config=base.yaml --config=overrides.yamlOptions
| Flag | What it does |
|---|---|
| validate | Validate config and exit (no run) |
| --config <file> | Config file path or URI (repeatable) |
| --config "yaml:..." | Inline YAML via the yaml provider |
| --feature-gates <g> | Enable feature gates affecting validation |
In CI
Run otelcol validate on the exact binary distribution you deploy. A config that validates on otelcol-contrib can fail on core otelcol because the component is not compiled in. The non-zero exit makes it a clean gate with no log parsing.
Common errors in CI
"error: failed to get config: ... error decoding 'receivers': unknown type: \"otlp/foo\"" means a component is not in this distribution (use contrib) or is misspelled. "service::pipelines::traces: references processor \"batch\" which is not configured" means a pipeline lists a component you never defined. "cannot unmarshal !!str into int" flags a wrong value type. Each fails the validate with a non-zero exit.