thanos-io/thanos · error

read query instant response

Error message

read query instant response

What it means

This error wraps any non-2xx failure from the HTTP request Prometheus makes to the /api/v1/query endpoint during QueryInstant. The req2xx helper only returns a body when the server responds with a 2xx status, so any 4xx/5xx response (bad PromQL, bad auth, server error) or transport failure surfaces here wrapped with the message 'read query instant response'. It indicates the query request itself failed before any response body could be decoded.

Solutions

1. Log the wrapped error's cause (errors.Cause) to see the underlying HTTP status and Prometheus 'error' message, then fix the query or URL it points to
2. Verify the base URL/host points at a reachable Prometheus /api/v1 endpoint (curl the same query manually)
3. Check that required auth headers are set via opts.HTTPHeaders or client configuration
4. Validate the PromQL expression (e.g. with promtool check or parser) before sending
5. Add retry with backoff for transient 5xx/timeouts

Example fix

// before
result, _, warn, err := client.PromqlQueryInstant(ctx, opts) // err: read query instant response: ...
// after
if err != nil {
    if cause := errors.Cause(err); cause != nil {
        log.Printf("instant query failed: %v", cause) // inspect real HTTP status/error
    }
    // validate query first:
    if _, err := parser.ParseExpr(opts.Query); err != nil {
        return fmt.Errorf("invalid PromQL %q: %w", opts.Query, err)
    }
}

// validate reachability and query before calling
if u, err := url.Parse(baseURL); err != nil || u.Scheme == "" || u.Host == "" {
    return fmt.Errorf("invalid prometheus baseURL: %q", baseURL)
}
if _, err := parser.ParseExpr(query); err != nil {
    return fmt.Errorf("invalid PromQL: %w", err)
}

result, _, warn, err := client.PromqlQueryInstant(ctx, opts)
if err != nil {
    if errors.Is(err, context.DeadlineExceeded) || isServerError(errors.Cause(err)) {
        // retry with backoff
    }
    return fmt.Errorf("instant query failed: %w", errors.Cause(err))
}

When it happens

Trigger: PromqlQueryInstant issues an instant query whose HTTP response status is not 2xx: invalid PromQL (400), wrong credentials (401/403), nonexistent endpoint/proxy path (404), timeouts or gateway errors (502/503/504), or connection errors to the Prometheus server.

Common situations: Misconfigured Prometheus URL or reverse-proxy path; malformed PromQL expression rejected by the server; missing auth token/headers; Prometheus temporarily down or overloaded; network egress blocked in the cluster.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

• failed to validate prometheus flags
• perform request against
• request config against
• read query range response
• request metric against

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

Appendix: source

Thrown at pkg/promclient/promclient.go:456

	}

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

	level.Debug(c.logger).Log("msg", "querying instant", "url", u.String())

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

	method := opts.Method
	if method == "" {
		method = http.MethodGet
	}

	body, _, err := c.req2xx(ctx, &u, method, opts.HTTPHeaders)
	if err != nil {
		return nil, nil, nil, errors.Wrap(err, "read query instant 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)