🚨 OpenTelemetry Error Guide: 'receivers: unknown type' — Fix Unrecognized Collector Components

Overview

The Collector builds each component from a registered factory keyed by its type. If the config names a type that no factory in the running binary recognizes, decoding fails before any pipeline starts, and the Collector lists the valid types it does know:

Error: failed to get config: cannot unmarshal the configuration: error decoding 'receivers': unknown type: "otlpp" for id: "otlpp" (valid values: [otlp hostmetrics prometheus filelog ...])

The same message shape appears for exporters, processors, and extensions:

Error: failed to get config: cannot unmarshal the configuration: error decoding 'exporters': unknown type: "prometheusremotewrit" for id: "prometheusremotewrit"

The error means the component type (the part before any /name suffix) is either misspelled or simply not compiled into this Collector distribution — the core otelcol binary ships far fewer components than otelcol-contrib.

Symptoms

• The Collector exits at startup with unknown type: "<type>" and never opens a port.
• The message lists valid values: [...] — the components actually registered in this binary.
• The failing id is a receiver, exporter, processor, or extension type you expected to exist.
• The config works on one host or image but fails on another running a different distro.
• A component documented on the OpenTelemetry site is missing from the valid values list.
• otelcol components output does not include the type you referenced.

Common Root Causes

• Misspelled type — otlpp, prometheusremotewrit, or batchh; a single wrong character means no factory matches.
• Wrong distribution — the component lives only in otelcol-contrib, but the running binary is core otelcol.
• Custom/OCB build missing the component — an OpenTelemetry Collector Builder manifest omitted the module that provides the type.
• Type vs named-ID confusion — writing otlp/2 as the type instead of using otlp as the type with a /2 instance name.
• Deprecated or renamed component — an old type name that was removed or renamed between Collector releases.
• Vendor-specific component — a proprietary exporter that isn’t in the open-source contrib distro at all.

Diagnostic Workflow

First, ask the binary which components it actually has. This is the authoritative list to compare against your config:

# List every receiver/exporter/processor/extension compiled into this binary
otelcol-contrib components | less
# Confirm which distribution and version is running
otelcol-contrib --version

Validate the config to get the exact offending id and the valid-values hint:

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

Fix a spelling mistake by matching the registered type exactly. The type is the map key (before any / suffix), so correct it there:

receivers:
  otlpp:                     # WRONG: no factory named "otlpp"
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

receivers:
  otlp:                      # CORRECT: registered type
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

If the type is spelled correctly but absent from components, you are on the wrong distribution. Switch to otelcol-contrib (which bundles the community components) or rebuild with the OpenTelemetry Collector Builder including the module:

# Confirm the contrib image/binary provides the component before deploying
otelcol-contrib components | grep -E 'otlp|prometheus|filelog|hostmetrics'

Example Root Cause Analysis

A config authored for otelcol-contrib was rolled out to a fleet where the base image had been slimmed to the core otelcol binary to reduce size. The config used the filelog receiver to tail application logs. On the slimmed hosts the Collector crash-looped with error decoding 'receivers': unknown type: "filelog", and the valid values list conspicuously lacked filelog because the core distribution does not include it. The type was spelled correctly; the binary simply didn’t have the factory.

The fix had two parts. First, the base image was reverted to otelcol-contrib, which registers filelog and the other community receivers, so the same config decoded cleanly. Second, the team standardized on a single distribution across environments and added otelcol-contrib components | grep filelog as a smoke check in the image build, so a future slim-down that dropped a required component would fail the build rather than crash-loop in production. Once the correct distro was in place, the unknown type error disappeared.

Prevention Best Practices

• Pin one Collector distribution (usually otelcol-contrib) across every environment to avoid missing-component surprises.
• Before deploying a config, run otelcol-contrib components and confirm every type you use is listed.
• Treat the valid values: [...] hint in the error as the ground truth for what this binary supports.
• Remember type/name IDs: the part before the slash is the type and must be registered; the suffix is just an instance label.
• When building with OCB, keep the manifest’s module list in review so a needed component is never dropped.
• Gate deploys on otelcol-contrib validate so a misspelled or unavailable type fails CI, not the pod.

Quick Command Reference

# List all components compiled into the running binary
otelcol-contrib components

# Check a specific component is available
otelcol-contrib components | grep -w otlp

# Validate config and surface the unknown-type id
otelcol-contrib validate --config /etc/otelcol-contrib/config.yaml

# Confirm distribution and version
otelcol-contrib --version

Conclusion

unknown type in a receivers, exporters, or processors block means the component type you named is either misspelled or not compiled into the running Collector. Compare the failing id against otelcol-contrib components: fix the spelling if it’s a typo, or switch to the distribution (or OCB build) that actually registers the component. Standardizing on one distro and validating configs in CI keeps this startup crash out of production.

Related

• OpenTelemetry Error Guide: ‘failed to parse config’
• OpenTelemetry Error Guide: ‘references exporter which is not configured’
• OpenTelemetry Error Guide: ‘rpc error: code = Unimplemented’