🚨 Loki Error Guide: 'max entries limit per query exceeded' — Cap Results, Aggregate, and Paginate

Overview

Loki rejects a query when the number of log lines it would return exceeds the per-query entry cap. The query frontend or querier returns an HTTP 400 with a message like this:

max entries limit per query exceeded, limit > max_entries_limit (10000 > 5000)

The cap is controlled by limits_config.max_entries_limit_per_query (default 5000). It applies to raw log-line queries — a stream selector plus optional line filters that returns individual entries — and it protects queriers and clients from being asked to marshal an unbounded result set into memory. Unlike a rate limit at ingest, this is a read-path guardrail: nothing is dropped from storage, Loki simply refuses to hand back more lines than the limit in a single query. The limit value in the message is what the request asked for; the max_entries_limit is the configured ceiling.

Symptoms

• A Grafana Explore panel or logcli query with a high --limit fails with a 400 and max entries limit per query exceeded.
• The same query with a smaller limit or a tighter time range returns results normally.
• The message shows two numbers, e.g. (10000 > 5000) — requested versus allowed.
• Dashboards that dump raw logs over long windows fail while metric/aggregation panels on the same data work.
• Automated log exporters or scripts that request tens of thousands of lines in one call break after a limit change.

Common Root Causes

• A client asking for more lines than the cap — Grafana’s line limit or logcli --limit set above max_entries_limit_per_query.
• Raw log dumps over wide ranges where the intent is really aggregation, not reading every line.
• A recently lowered max_entries_limit_per_query now rejecting queries that used to pass.
• Export/ETL jobs pulling bulk logs in a single request instead of paginating.
• Missing filters so a broad selector matches far more entries than needed.

How to diagnose

1. Read the two numbers in the error — (requested > allowed). If requested is a round client default (5000, 10000), the fix is on the client; if allowed is surprisingly low, the config changed.

2. Confirm the configured cap on the running Loki:

   curl -s http://loki.internal:3100/config \
     | grep -i max_entries_limit_per_query

3. Check the client’s requested limit — in Grafana, the panel/Explore “Line limit”; in logcli, the --limit flag; in code, the limit query parameter.

4. Decide intent — are you actually reading individual lines, or computing a count/rate? If it is really aggregation, this is a metric query, not a raw log query, and the cap does not apply.

5. Reproduce with a small limit to confirm the query is otherwise valid:

   logcli query '{app="checkout", env="staging"}' --limit 100 --since 1h

Fixes

Lower the requested limit to sit under the cap when you only need a sample:

logcli query '{app="checkout"}' --limit 1000 --since 1h

Switch to a metric query when you want counts, not lines — aggregation is not bound by the entry cap and is far cheaper:

# Instead of dumping every error line, count them
sum by (app) (count_over_time({app="checkout"} |= "error" [5m]))

Paginate large exports with the logcli batch flag so each request stays under the cap while you still retrieve everything:

# --batch pages through results in chunks under the entry limit
logcli query '{app="checkout"}' --limit 100000 --batch 1000 --since 24h

Raise the cap deliberately if a legitimate workflow needs more lines per query — do it as a scoped per-tenant override, not a blanket global bump, and remember every querier must marshal that many entries:

limits_config:
  max_entries_limit_per_query: 5000   # global default

# per-tenant override (runtime overrides file):
# overrides:
#   export-tenant:
#     max_entries_limit_per_query: 20000

Add specific label matchers and line filters so the query returns only relevant entries and naturally falls under the limit.

What to watch out for

• Raising max_entries_limit_per_query increases querier memory per request; a big cap plus concurrent heavy queries can OOM queriers — pair any increase with querier headroom.
• --batch in logcli paginates client-side; it does not bypass the cap, it just keeps each page under it. That is the safe way to pull large volumes.
• A metric query dodges this limit but has its own guardrails (max_query_bytes_read, series limits) — do not treat aggregation as unlimited.
• Grafana has its own separate line-limit setting; a user may hit the panel limit or the Loki limit first, so check both when results look truncated.
• If you keep raising the cap to dump raw logs, that is usually a sign the workflow wants aggregation or an export pipeline, not interactive queries.

Related

• Loki Error Guide: ‘context deadline exceeded’ — the timeout you hit next when queries scan too much.
• Loki Error Guide: ‘the query time range exceeds the limit’ — the sibling read-path guardrail on range length.
• Loki Error Guide: ‘too many outstanding requests’ — what overloads the read path when big queries pile up.