🚨 OpenTelemetry Error Guide: ''exporters' has invalid keys' — Fix Collector Config Typos

Overview

The Collector unmarshals each component’s settings with strict validation: any key that a component’s config struct does not define is rejected outright. A single mistyped field name therefore stops startup and the Collector points at the unknown key:

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

error decoding 'exporters': 'exporters' has invalid keys: endpont

The same strict check fires for nested keys and for other component kinds, for example:

error decoding 'receivers': 'receivers' has invalid keys: protocol

The message means you supplied a key the component does not recognize — usually a typo (endpont for endpoint), a field placed at the wrong nesting level, or a setting that belongs to a different component.

Symptoms

• The Collector fails at startup with has invalid keys: <key> naming the exact unknown field.
• The offending key is a near-miss spelling of a real setting (endpont, timout, headrs).
• The error appears immediately after adding or editing one line of a component’s config.
• A field that works under one component is rejected under another because it doesn’t belong there.
• otelcol-contrib validate reports the same invalid-keys message.
• Removing or correcting the single key lets the Collector start.

Common Root Causes

• Simple typo — endpont instead of endpoint, timout instead of timeout, compresion instead of compression.
• Wrong nesting level — a valid key placed one indent too high or too low so it lands where it isn’t defined.
• Setting on the wrong component — putting an exporter-only key under a receiver, or vice versa.
• Deprecated/renamed field — using an old key name that a newer Collector release removed.
• Copy-paste from a different distro — a vendor field that isn’t part of the open-source component’s schema.
• YAML indentation drift — a key intended as a child of tls: or sending_queue: merges into the parent map instead.

Diagnostic Workflow

Validate first — the message names the exact key the component rejected, which is the fastest path to the fix:

otelcol-contrib validate --config /etc/otelcol-contrib/config.yaml
journalctl -u otelcol-contrib --since '10 min ago' | grep -i 'invalid keys'

Locate the bad key. Here endpont under the otlp exporter is a typo for endpoint:

exporters:
  otlp:
    endpont: backend.example.com:4317   # WRONG: not a real key
    tls:
      insecure: false

Correct the spelling to the field the component actually defines:

exporters:
  otlp:
    endpoint: backend.example.com:4317  # CORRECT
    tls:
      insecure: false
    retry_on_failure:
      enabled: true
    sending_queue:
      enabled: true
      queue_size: 5000

When you are unsure of the exact key names a component supports, print the components list and cross-check against the documented settings for that type:

# Confirm the component and consult its config keys
otelcol-contrib components | grep -w otlp

Watch for the wrong-nesting variant: a key like insecure belongs under tls:, not directly under the exporter. If validation still fails after fixing spelling, check indentation:

# Reveal indentation so a child key isn't sitting in the parent map
grep -nE 'endpoint|insecure|compression' /etc/otelcol-contrib/config.yaml

Example Root Cause Analysis

During a hurried edit to point traces at a new backend, an engineer typed endpont: under the otlp exporter. The Collector refused to start with 'exporters' has invalid keys: endpont, and because the agent was managed by systemd it entered a restart loop — no telemetry left the host. The value on the line was correct; only the key name was wrong, so a glance at the file didn’t reveal the problem until they read the error’s named key.

The fix had two parts. First, endpont was corrected to endpoint, and the config validated cleanly. Second, the team added a mandatory otelcol-contrib validate step to the config deployment job, so strict-key validation runs before the file ever reaches a host. Because the Collector’s decoder rejects any unknown key by design, that single CI gate catches every typo of this class — misspelled endpoint, timeout, compression, or headers — before it can crash-loop a production agent.

Prevention Best Practices

• Run otelcol-contrib validate on every config change; strict-key validation flags the exact bad field.
• Read the named key in the error first — it tells you precisely which line to fix.
• Keep an editor schema or snippet library of correct component keys to avoid near-miss typos.
• Verify indentation so child settings (like insecure under tls:) don’t leak into the parent map.
• Don’t copy component fields between distributions or versions without confirming the key still exists.
• Gate deploys on validation in CI so a one-character typo never crash-loops a live Collector.

Quick Command Reference

# Validate config and reveal the invalid key
otelcol-contrib validate --config /etc/otelcol-contrib/config.yaml

# Watch the startup failure naming the bad key
journalctl -u otelcol-contrib --since '10 min ago' | grep -i 'invalid keys'

# Confirm a component exists before checking its keys
otelcol-contrib components | grep -w otlp

# Restart after correcting the typo
systemctl restart otelcol-contrib

Conclusion

'exporters' has invalid keys is the Collector’s strict decoder rejecting a field name it doesn’t recognize — nearly always a typo, a mis-nested key, or a setting on the wrong component. The error names the exact key, so the fix is usually a one-character correction. Validate every config change in CI with otelcol-contrib validate and the entire family of typo-driven startup crashes is caught before deploy.

Related

• OpenTelemetry Error Guide: ‘failed to parse config’
• OpenTelemetry Error Guide: ‘references exporter which is not configured’
• OpenTelemetry Error Guide: ‘address already in use’