thanos-io/thanos · error

received message larger than max

Error message

received message larger than max (%d vs %d)

What it means

WriteJSONResponse marshals v to JSON and writes it to the HTTP response body; if the serialized payload exceeds the allowed maximum message size it is rejected with this error. The message reports the actual size versus the configured maximum. It exists to prevent unbounded responses from exhausting memory or violating gRPC/message-size contracts.

Solutions

1. Reduce the response size (paginate, limit results, or stream instead of buffering the whole JSON)
2. Increase the configured max message size if legitimately large responses are expected
3. Compress the response (e.g. gzip) so the payload fits within limits
4. Switch the endpoint to a streaming variant if the library provides one

Example fix

// before
util.WriteJSONResponse(w, hugeResult)
// after
w.Header().Set("Content-Encoding", "gzip")
gz := gzip.NewWriter(w)
util.WriteJSONResponse(gzWriter{ResponseWriter: w, Writer: gz}, paginatedResult)

data, err := json.Marshal(v)
if err != nil { return err }
if len(data) > maxMessageSize {
    return fmt.Errorf("response too large: %d > %d", len(data), maxMessageSize)
}

if err := util.WriteJSONResponse(w, v); err != nil {
    if strings.Contains(err.Error(), "received message larger than max") {
        http.Error(w, "response too large; paginate the request", http.StatusRequestEntityTooLarge)
        return
    }
    http.Error(w, err.Error(), http.StatusInternalServerError)
}

When it happens

Trigger: Calling WriteJSONResponse (directly or through RenderHTTPResponse) with a value whose json.Marshal output exceeds the configured max message size.

Common situations: Handlers returning very large query results or bulk exports over HTTP APIs, or limits tuned for gRPC (e.g. 4MB/16MB defaults) being applied to JSON responses.

Understand the failure class

Background: payload too large / request exceeds maximum size: why libraries cap bytes and how to fix oversize payloads — this error's family across 50 libraries.

Related errors

• error marshaling response
• unmarshal query instant response
• read meta
• creating request to downstream URL
• error starting web server

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

Appendix: source

Thrown at internal/cortex/util/http.go:55

}

func (b *BasicAuth) RegisterFlagsWithPrefix(prefix string, f *flag.FlagSet) {
	f.StringVar(&b.Username, prefix+"basic-auth-username", "", "HTTP Basic authentication username. It overrides the username set in the URL (if any).")
	f.StringVar(&b.Password, prefix+"basic-auth-password", "", "HTTP Basic authentication password. It overrides the password set in the URL (if any).")
}

// IsEnabled returns false if basic authentication isn't enabled.
func (b BasicAuth) IsEnabled() bool {
	return b.Username != "" || b.Password != ""
}

// WriteJSONResponse writes some JSON as a HTTP response.
func WriteJSONResponse(w http.ResponseWriter, v any) {
	w.Header().Set("Content-Type", "application/json")

	data, err := json.Marshal(v)
	if err != nil {
		http.Error(w, err.Error(), http.StatusInternalServerError)
		return
	}

	// We ignore errors here, because we cannot do anything about them.
	// Write will trigger sending Status code, so we cannot send a different status code afterwards.
	// Also this isn't internal error, but error communicating with client.
	_, _ = w.Write(data)
}

// WriteYAMLResponse writes some YAML as a HTTP response.
func WriteYAMLResponse(w http.ResponseWriter, v any) {
	// There is not standardised content-type for YAML, text/plain ensures the
	// YAML is displayed in the browser instead of offered as a download
	w.Header().Set("Content-Type", "text/plain; charset=utf-8")

	data, err := yaml.Marshal(v)
	if err != nil {
		http.Error(w, err.Error(), http.StatusInternalServerError)

View on GitHub (pinned to 35b8b99117)