🚨 Loki Error Guide: 'the query time range exceeds the limit' — Split the Range or Raise max_query_length

Overview

Loki refuses to run a query whose start-to-end span is longer than max_query_length. The frontend returns:

the query time range exceeds the limit (query length: 745h37m0s, limit: 721h0m0s)

A closely related variant appears when you query further back than max_query_lookback allows:

the query time range exceeds the limit (query length ... , limit ...) or is beyond the max lookback period

Both are read-path protections that stop a single query from scanning an unbounded amount of the index and object storage.

Symptoms

• A dashboard set to “Last 90 days” or an ad-hoc --from/--to over weeks fails instantly.
• Short ranges on the same query succeed; only the long span fails.
• The error names both the requested length and the limit, so the gap is explicit.
• Grafana shows the error on panel load; logcli prints it before any streaming.
• Frontend/querier logs show the query time range exceeds the limit.

Common Root Causes

• Panel or query range wider than max_query_length — a 90-day dashboard against a 30-day (721h) limit.
• Range beyond max_query_lookback — querying older than retention or the configured lookback window.
• Metric queries over long spans — count_over_time(...[30d])-style ranges combined with a wide dashboard window.
• Default limit left conservative — max_query_length never raised for legitimate long-range analysis.
• Grafana “zoom to fit”/auto ranges — a user widening the time picker past the limit unintentionally.
• Alerting/recording rules with long ranges — a ruler rule whose evaluation range exceeds the limit.

Diagnostic Workflow

Confirm the configured limits:

limits_config:
  max_query_length: 721h        # ~30 days
  max_query_lookback: 744h      # ~31 days; must be >= retention you want queryable
  max_query_range: 0            # per-subquery range cap (0 = unlimited)

Check the effective runtime values:

logcli --addr=http://loki-gateway/ config \
  | grep -iE 'max_query_length|max_query_lookback|max_query_range'

Split a long ad-hoc query into windows that each fit under the limit:

# Instead of one 90-day query, iterate 30-day windows
logcli query '{namespace="payments"} |= "error"' \
  --from="2026-04-10T00:00:00Z" --to="2026-05-10T00:00:00Z" --limit=5000

For dashboards, let the frontend split the range automatically by ensuring query splitting is on:

query_range:
  split_queries_by_interval: 30m
  parallelise_shardable_queries: true

If long ranges are a legitimate requirement for one tenant, raise the limit via an override:

overrides:
  analytics-tenant:
    max_query_length: 2160h     # 90 days
    max_query_lookback: 2160h

Example Root Cause Analysis

A data team’s compliance dashboard set to “Last 90 days” broke with query length: 2160h0m0s, limit: 721h0m0s. The cluster’s global max_query_length was 721h (30 days) to protect shared queriers, but this tenant genuinely needed quarter-long audit views.

Rather than raise the global limit — which would let any tenant launch 90-day scans and starve the read path — they added a per-tenant override raising max_query_length and max_query_lookback to 2160h only for analytics-tenant, and confirmed split_queries_by_interval: 30m was enabled so the frontend fanned the 90-day range into parallel sub-queries across queriers. The dashboard loaded, other tenants kept their protective 30-day cap, and querier memory stayed flat because the work was split and cached rather than run as one giant scan.

Prevention Best Practices

• Set max_query_length and max_query_lookback to match your real retention and the longest dashboards you support, no larger.
• Use per-tenant overrides for the few tenants that need long-range analysis instead of loosening the global limit.
• Keep split_queries_by_interval enabled so long ranges are parallelized and cached rather than run as one scan.
• Educate dashboard authors to avoid unbounded “All time” ranges on high-volume tenants.
• Ensure max_query_lookback is at least your retention so retained data stays queryable.
• Bound ruler/recording-rule ranges so evaluation never exceeds the limit.

Quick Command Reference

# Effective range limits
logcli --addr=http://loki-gateway/ config | grep -iE 'max_query_length|lookback|max_query_range'

# Run a windowed query under the limit
logcli query '{namespace="payments"}' --from="2026-05-01T00:00:00Z" --to="2026-05-30T00:00:00Z"

# Confirm query splitting is active (frontend config)
logcli --addr=http://loki-gateway/ config | grep -i split_queries_by_interval

Conclusion

the query time range exceeds the limit is Loki enforcing max_query_length (span) or max_query_lookback (how far back) so no single query can scan unbounded storage. For one-off analysis, split the range into windows under the limit. For dashboards that legitimately need long ranges, grant a scoped per-tenant override rather than loosening the global cap, and keep query splitting on so the range is parallelized and cached. Size the limits to your retention and longest supported dashboard — no more.