Skip to content

OpenTelemetry Collector Configuration Parse Error Fix

DodaTech Updated 2026-06-24 2 min read

In this tutorial, you'll learn about OpenTelemetry Collector Configuration Parse Error Fix. We cover key concepts, practical examples, and best practices.

Your OpenTelemetry Collector fails to start with error reading config: yaml: line 8: did not find expected key — the configuration file has syntax errors, the YAML indentation is wrong, or a required section is missing.

The Problem

receivers:
  otlp:
    protocols:
    grpc:
        endpoint: 0.0.0.0:4317
    http:
      endpoint: 0.0.0.0:4318
exporters:
  logging:
    loglevel: debug
Error: cannot start the OpenTelemetry Collector: error reading config:
  yaml: line 4: did not find expected key

The YAML indentation is inconsistent — grpc is at the same level as protocols instead of being nested under it, and the exporter section is missing the service pipeline definition.

Step-by-Step Fix

1. Fix YAML indentation

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

2. Add the service pipeline

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

exporters:
  logging:
    loglevel: debug

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [logging]

3. Validate config before starting

# Check YAML syntax
otelcol --validate --config otel-collector-config.yaml

# Use a YAML linter
yamllint otel-collector-config.yaml

4. Use environment variable substitution

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: ${MY_ENDPOINT}:4317

exporters:
  otlp:
    endpoint: ${UPSTREAM_ENDPOINT}:4317
    headers:
      authorization: Bearer ${API_TOKEN}

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [otlp]
export MY_ENDPOINT=0.0.0.0
export UPSTREAM_ENDPOINT=jaeger.example.com
export API_TOKEN=abc123
otelcol --config otel-collector-config.yaml

5. Enable config validation

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

processors:
  batch:
    timeout: 1s
    send_batch_size: 1024

exporters:
  logging:
    loglevel: info
  otlp:
    endpoint: jaeger:4317

extensions:
  health_check:
    endpoint: 0.0.0.0:13133

service:
  extensions: [health_check]
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [logging, otlp]

Expected output:

2026-06-24T10:00:00.000Z INFO    service/collector.go:123  Starting OpenTelemetry Collector...
2026-06-24T10:00:00.050Z INFO    service/collector.go:200  Everything is ready.

Prevention Tips

  • Validate config with otelcol --validate before deploying
  • Use consistent 2-space YAML indentation throughout
  • Use environment variable substitution for sensitive values
  • Add health_check extension for monitoring collector status
  • Keep config files in version control with syntax checking in CI

Common Mistakes with collector config

  1. Placing the wildcard pattern first in case expressions, making all subsequent patterns unreachable
  2. Using head and tail instead of pattern matching, causing runtime errors on empty lists
  3. Forgetting that lazy evaluation defers computation until the value is forced, causing space leaks with unevaluated thunks

These mistakes appear frequently in real-world OPENTELEMETRY code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ

### What are the required sections in a collector config?

The minimal config needs receivers, exporters, and service.pipelines. Each pipeline connects receivers to exporters (with optional processors in between). Without a pipeline, the collector starts but does nothing.

Can I hot-reload the collector config?

Yes, send SIGHUP to the collector process: kill -HUP <pid>. The collector reloads config without restarting. Alternatively, use the --config flag with a directory and the collector watches for file changes.

How do I debug config loading issues?

Start with --log-level debug to see detailed config parsing output. Use --validate to check syntax without starting pipelines. Check the collector's own metrics endpoint (usually :8888/metrics) for configuration-related metrics.

Built by the developers of DodaTech

Doda Browser, DodaZIP & Durga Antivirus Pro