🚨 OpenTelemetry Error Guide: 'unknown compression type' — Fix OTLP Exporter Compression Config

Overview

OTLP exporters can compress each request, but the compression: field only accepts a fixed set of algorithm names. If the value isn’t one the exporter recognizes, the Collector fails to construct the exporter and rejects the config at startup:

Error: failed to build pipelines: failed to create "otlp" exporter: unknown compression type "gzp"
2026/07/12 08:33:19 collector server run finished with error: invalid configuration

The HTTP OTLP exporter surfaces the same validation:

Error: failed to create "otlphttp" exporter: unknown compression type "gzp"

The message means compression: was set to a string that isn’t a supported codec. Valid values are none, gzip, zstd, snappy, zlib, and deflate — anything else (a typo like gzp, or an unsupported name) is rejected.

Symptoms

• The Collector fails at startup and names the otlp or otlphttp exporter.
• Logs show unknown compression type "<value>" with your mistyped codec.
• The value is a near-miss like gzp, gz, or zstdd, or an unsupported name like lz4.
• The failure began right after enabling or changing compression on an exporter.
• Every pipeline using that exporter is down.
• otelcol-contrib validate reports the same message.

Common Root Causes

• Typo in the codec name — gzp for gzip, zstdd for zstd, snapy for snappy.
• Unsupported algorithm — a real compressor (lz4, br/brotli) that OTLP exporters don’t offer.
• Case or whitespace — a stray space or capitalization that doesn’t match the expected lowercase token.
• Templated value — a Helm value or env expansion rendered an unexpected string into compression:.
• Wrong field — putting a codec where a boolean or another setting was expected, or vice versa.
• Copy-paste from another tool — a compression name valid in a different system but not in OTLP exporters.

Diagnostic Workflow

Validate to confirm the exporter and see the exact rejected value:

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

Find the offending field. Here gzp is a typo for gzip on the OTLP gRPC exporter:

exporters:
  otlp:
    endpoint: backend.example.com:4317
    compression: gzp          # WRONG: not a valid codec
    tls:
      insecure: false

Set it to a supported value. gzip is the safe, widely compatible default; zstd and snappy trade CPU for ratio/speed:

exporters:
  otlp:
    endpoint: backend.example.com:4317
    compression: gzip         # valid: none | gzip | zstd | snappy | zlib | deflate
    tls:
      insecure: false
    retry_on_failure:
      enabled: true
    sending_queue:
      enabled: true
      queue_size: 5000

If you want to disable compression explicitly, use none rather than leaving an unsupported string:

exporters:
  otlphttp:
    endpoint: https://backend.example.com:4318
    compression: none         # explicitly no compression
    headers:
      authorization: "Bearer ${API_KEY}"

Confirm the backend accepts the codec you choose — a valid-but-unsupported-by-the-server algorithm can cause export errors even though the config loads:

# After fixing, watch that exports actually succeed
journalctl -u otelcol-contrib -f | grep -iE 'exporter|compress|failed'

Example Root Cause Analysis

A team wanted to cut egress cost by compressing traces to a vendor OTLP endpoint. In the exporter they typed compression: gzp, intending gzip. The Collector failed to build pipelines with unknown compression type "gzp" and, being systemd-managed, entered a restart loop that took down all export until someone read the log. The value looked plausible at a glance, so the typo wasn’t obvious until the error named it.

The fix had two parts. First, gzp was corrected to gzip, and the config validated and started; a quick check of the vendor’s docs confirmed the endpoint accepts gzip, so exports succeeded rather than trading the config error for a runtime one. Second, the team added otelcol-contrib validate to their config CI, which constructs each exporter and therefore rejects any unsupported compression: value before deploy. The restart loop cleared and compressed exports flowed immediately.

Prevention Best Practices

• Use only the supported codecs: none, gzip, zstd, snappy, zlib, deflate.
• Prefer gzip for broad compatibility unless you’ve confirmed the backend supports zstd/snappy.
• Set compression: none explicitly to disable, rather than an empty or unsupported value.
• Verify the receiving backend accepts your chosen codec so a valid config doesn’t fail at runtime.
• Sanity-check templated/env-expanded values that feed compression:.
• Validate configs in CI so a typo like gzp fails the pull request, not the running Collector.

Quick Command Reference

# Validate config and reveal the rejected compression value
otelcol-contrib validate --config /etc/otelcol-contrib/config.yaml

# Watch the startup failure
journalctl -u otelcol-contrib --since '10 min ago' | grep -i 'compression type'

# Check the compression setting in the config
grep -n 'compression:' /etc/otelcol-contrib/config.yaml

# After fixing, confirm exports succeed
journalctl -u otelcol-contrib -f | grep -iE 'exporter|failed'

Conclusion

unknown compression type means the OTLP exporter’s compression: field was set to something outside the supported set. Correct it to one of none, gzip, zstd, snappy, zlib, or deflate — gzip is the safe default — and confirm your backend accepts it. Validating configs in CI, where each exporter is actually constructed, catches an invalid codec before it can crash-loop a production Collector.

Related

• OpenTelemetry Error Guide: ‘failed to parse config’
• OpenTelemetry Error Guide: ‘ResourceExhausted: received message larger than max’
• OpenTelemetry Error Guide: ‘connection refused’ to the Collector