🚨 Loki Error Guide: 'label value too long' — Keep High-Entropy Strings Out of Your Stream Labels

Overview

Loki’s distributor enforces a maximum byte length on both label names and label values as it validates a push. When a value (or name) exceeds the ceiling, the push is rejected with an HTTP 400 and a message like this:

label value too long: <value>

The name variant looks nearly identical:

label name too long: <name>

These limits come from limits_config.max_label_value_length (default 2048) and limits_config.max_label_name_length (default 1024). Rejected pushes increment loki_discarded_samples_total with reason="label_value_too_long" or reason="label_name_too_long". A long label value is almost always a symptom of the same anti-pattern behind cardinality explosions: someone put a URL, a UUID, a full log message, or a stack trace into a label instead of into the log line. The right fix is to keep that data in the body and extract it at query time.

Symptoms

• Pushes fail with HTTP 400 and label value too long (or label name too long) in the distributor logs.
• loki_discarded_samples_total{reason="label_value_too_long"} or {reason="label_name_too_long"} increases.
• Only certain event types (errors carrying stack traces, requests carrying full URLs) get dropped, while shorter logs ingest fine.
• The agent logs repeated failed batches for a specific target that emits long dynamic strings.
• Stream cardinality was already climbing before the rejections, because the long values were also unique per event.

Common Root Causes

• URLs or query strings promoted to labels — a path or url label carries the full request URL including query parameters, easily blowing past 2048 bytes.
• UUIDs, tokens, or hashes as label values — request_id, session_token, or a content hash used as a label, which is both long and unbounded in cardinality.
• Full messages or stack traces in a label — a msg or error label containing the entire log line or a multi-line stack trace.
• Long dynamic strings used as label names — a pipeline that turns arbitrary JSON keys into label names, so a long key trips max_label_name_length.
• Concatenated context strings — a context label built by joining several fields, which grows without bound as inputs vary.
• Base64 or serialized payloads — encoded blobs accidentally mapped into a label rather than the log body.

How to diagnose

1. Confirm the exact validation error and whether it is the value or the name variant:

   kubectl logs -l app=loki,component=distributor -n loki --tail=300 \
     | grep -E 'label (value|name) too long'

2. Break down discards by reason to size the impact:

   sum by (reason) (
     rate(loki_discarded_samples_total{reason=~"label_(value|name)_too_long"}[5m])
   )

3. Find which label is oversized by inspecting the stream’s label set for the offending target:

   logcli series '{app="api"}' --analyze-labels \
     --addr=https://loki-gateway/ --org-id=tenant-a

4. Read the effective length limits in force for the tenant:

   limits_config:
     max_label_value_length: 2048
     max_label_name_length: 1024

5. Locate the offending pipeline stage that maps a long field into a label:

   pipeline_stages:
     - json:
         expressions:
           url: request.url      # full URL, can exceed 2048 bytes
     - labels:
         url:                    # this is the problem

Fixes

Never map high-entropy or long values to labels — remove the offending labels mapping and leave the field in the log line, where length is bounded only by the much larger line-size limit:

pipeline_stages:
  - json:
      expressions:
        url: request.url
  # no 'labels:' stage for url — it stays in the log body

Extract the value at query time instead — parse it on read with | json or | logfmt, which costs nothing at ingest and keeps cardinality flat:

{namespace="prod", app="api"} | json | url=~"/checkout.*"

Attach long high-cardinality context as structured metadata — this keeps values queryable without making them stream labels subject to the label-value limit:

limits_config:
  allow_structured_metadata: true

Truncate in the agent when you genuinely need a short label — derive a bounded label (for example a route template) rather than the raw string, using a template stage in Promtail:

pipeline_stages:
  - template:
      source: route
      template: '{{ regexReplaceAll "\\?.*$" .url "" }}'   # strip query string
  - labels:
      route:

Raise the limit only as a stopgap — bump max_label_value_length just enough to unblock ingestion while you move the data out of labels, and revert it afterward:

limits_config:
  max_label_value_length: 4096   # temporary; fix the pipeline, then reduce

What to watch out for

• Raising max_label_value_length accepts the push but does not fix cardinality — long, unique values are still one stream each and will hurt ingester memory and index size.
• The line-size limit (max_line_size) is far larger than the label-value limit for a reason; keep big strings in the body where they belong.
• label name too long is rarer and usually means dynamic keys are being turned into label names — curate label names to a fixed, known set.
• Truncating a value into a label can still be high-cardinality if the truncated form varies a lot; prefer a normalized template (route, status class) over a raw substring.
• Dropped pushes are lost logs; watch loki_discarded_samples_total{reason=~"label_.*_too_long"} and treat any nonzero rate as an agent bug to fix.

Related

• Loki Error Guide: ‘Maximum active stream limit exceeded’ — the cardinality blowup that long, unique label values cause.
• Loki Error Guide: ‘Per stream rate limit exceeded’ — the throughput symptom of the same labeling mistakes.
• Loki Error Guide: ‘max line size exceeded’ — the body-side limit for the large strings you should move out of labels.