criticalIntermediateSymptom-first#opentelemetry#collector#config#startup#yaml

OpenTelemetry collector fails to start — invalid YAML config or missing receiver

Collector pod shows CrashLoopBackOff after config change

Likely source:configurationdeployment

Focused incident mode — strips away everything but this runbook.

Symptoms

  • Collector pod shows CrashLoopBackOff after config change
  • Collector logs show 'failed to load config' or 'invalid YAML'
  • Collector logs show 'receiver not found' or 'exporter not found'
  • Collector pod restarts immediately after startup with exit code 1

The otelcol-contrib image includes all standard components. If you use a custom collector build, always verify the available components with /otelcol-components after deploying. Config validation is best done in CI with otelcol validate.

Evidence to grab

Collect these artifacts before you change anything — they prove (or rule out) each cause.

  • Collector crash logs

    kubectl logs -n observability deploy/otel-collector --previous | tail -50

  • Collector config YAML

    kubectl get cm -n observability otel-collector-config -o yaml

Diagnostic flow

Run the steps in order, marking each claim confirmed or refuted. The evidence you gather feeds the ranked causes below.

Guided decision tree is ready.

Steps with commands, expected output, and pass/fail branches.

Ranked root causes

Evidence checklist

  • Collector logs show 'yaml: unmarshal errors' or 'invalid YAML'
  • Recent edit introduced an indentation error or missing colon
  • The config YAML is syntactically invalid

Confirm before fixing

kubectl get cm -n observability otel-collector-config -o yaml | grep -A100 'otel-collector-config.yaml' | tail -n +2 | python3 -c 'import sys,yaml; yaml.safe_load(sys.stdin.read())'
READ

Parse the YAML for syntax errors

Expected: yaml.YAMLError with line number

Fix

kubectl edit cm -n observability otel-collector-config
CHANGE

Fix the YAML indentation or syntax error

Resolution runbook

Apply from top to bottom after the cause is confirmed. Review every command before running it — risk tags are shown on each.

1
kubectl logs -n observability deploy/otel-collector --previous | grep -iE 'error|fatal|invalid|not found' | tail -20
READ

Read the crash logs for the exact error

2
kubectl get cm -n observability otel-collector-config -o yaml | grep -A100 'otel-collector-config.yaml' | tail -n +2 | python3 -c 'import sys,yaml; yaml.safe_load(sys.stdin.read())'
READ

Validate the YAML syntax

3
kubectl exec -n observability deploy/otel-collector -- /otelcol-components 2>&1 | head -30
READ

List available components in the collector binary

4
kubectl edit cm -n observability otel-collector-config
CHANGE

Fix the config YAML (syntax, component names, or pipeline references)

Prevention

  • Add otelcol validate to the CI pipeline to catch config errors before deploy.
  • Use the otelcol-contrib image for full component support.
  • Version-control the collector config and use ConfigMap checksums to trigger rollouts on change.
  • Test config changes in a staging collector before applying to production.

Related runbooks

Same stack, same failure family — worth a skim.

OpenTelemetry traces not arriving at the collector — export fails or batch processor abortscritical

Application exports traces but nothing appears in Jaeger/Tempo

OpenTelemetryIntermediate3 causes
Open runbook
Prometheus rules file fails config reload with parse errorhigh

Prometheus config reload fails with 'error parsing YAML' or 'parse error'

PrometheusIntermediate3 causes
Open runbook

Commands marked READ CHANGE DESTRUCTIVE — never run DESTRUCTIVE commands against production data you cannot restore. Copy → verify → execute.