thanos-io/thanos · error

read query range response

Error message

read query range response

What it means

QueryRange issues a GET to the /api/v1/query_range endpoint through c.req2xx, which requires a 2xx response. If the HTTP request fails at the transport level or the server returns a non-2xx status, the library wraps the error with 'read query range response'. This is the network/HTTP failure path for range queries.

Solutions

1. Check the wrapped inner error: if it's a status code, curl the same URL to see the upstream JSON error (e.g. 'query timeout, execution timeout' with 503) and tune --query.timeout / narrow the range or step.
2. Verify the endpoint address is reachable from this process (DNS, port, firewall, TLS certificates).
3. Retry with backoff for transient 5xx/unavailable responses; the client supports retries via TLSConfig / retry options where configured.
4. Reduce query cost (smaller range, larger step, more selective matchers) if the failure is a resource/size limit.

Example fix

// before
matrix, _, _, err := client.QueryRange(ctx, base, "up", start, end, 5, opts) // end-start = 90 days, step 5s
// after
matrix, _, _, err := client.QueryRange(ctx, base, "up", start, end, 60, opts) // larger step, narrower range
if err != nil {
    if strings.Contains(err.Error(), "503") { /* backoff and retry */ }
}

// Reachability pre-check before issuing a range query
conn, err := net.DialTimeout("tcp", host+":9090", 2*time.Second)
if err != nil {
    return fmt.Errorf("prometheus endpoint unreachable: %w", err)
}
conn.Close()

func isHTTPFailure(err error) bool {
    return err != nil && strings.Contains(err.Error(), "read query range response")
}

var matrix model.Matrix
backoff := time.Second
for i := 0; i < 3; i++ {
    m, _, _, err := client.QueryRange(ctx, base, q, st, en, step, opts)
    if err == nil { matrix = m; break }
    if !isHTTPFailure(err) || !strings.Contains(err.Error(), "50") { return err }
    time.Sleep(backoff); backoff *= 2
}

When it happens

Trigger: Calling QueryRange (via Exec) when the Prometheus endpoint is unreachable, the connection is refused or times out, TLS fails, or the server responds with a 4xx/5xx status (overloaded, bad request, auth failure).

Common situations: Prometheus down or restarting, wrong address/port in the store or query configuration, query_range hitting the max samples/timeout limit and returning 422/503, DNS failures, or mTLS/network policy blocking the call.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

• request metric against
• send request
• failed to validate prometheus flags
• perform request against
• request config against

AI-assisted analysis of thanos-io/thanos@35b8b99117 (2026-09-07). Data as JSON: /api/errors/d8e23f146bea4e62. Report an issue: GitHub.

Appendix: source

Thrown at pkg/promclient/promclient.go:561

	params.Add("step", strconv.FormatInt(step, 10))
	if !opts.DoNotAddThanosParams {
		if err := opts.AddTo(params); err != nil {
			return nil, nil, nil, errors.Wrap(err, "add thanos opts query params")
		}
	}

	u := *base
	u.Path = path.Join(u.Path, "/api/v1/query_range")
	u.RawQuery = params.Encode()

	level.Debug(c.logger).Log("msg", "range query", "url", u.String())

	span, ctx := tracing.StartSpan(ctx, "/prom_query_range HTTP[client]")
	defer span.Finish()

	body, _, err := c.req2xx(ctx, &u, http.MethodGet, opts.HTTPHeaders)
	if err != nil {
		return nil, nil, nil, errors.Wrap(err, "read query range response")
	}

	// Decode only ResultType and load Result only as RawJson since we don't know
	// structure of the Result yet.
	var m struct {
		Data struct {
			ResultType  string          `json:"resultType"`
			Result      json.RawMessage `json:"result"`
			Explanation *Explanation    `json:"explanation,omitempty"`
		} `json:"data"`

		Error     string `json:"error,omitempty"`
		ErrorType string `json:"errorType,omitempty"`
		// Extra fields supported by Thanos Querier.
		Warnings []string `json:"warnings"`
	}

	if err = json.Unmarshal(body, &m); err != nil {

View on GitHub (pinned to 35b8b99117)