JuliusBrussee/caveman · warning

kms: response exceeds limit

Error message

kms: %s response exceeds limit

What it means

The KMS response body exceeded maxResponseBytes. The client reads at most maxResponseBytes+1 bytes and fails closed if more data arrives, protecting against hostile or buggy servers returning unbounded payloads. The response was valid HTTP 200 but too large to trust.

Solutions

1. Check what the server is actually returning (curl the endpoint) — an HTML error/proxy page means the endpoint config is wrong.
2. If the payload is legitimately large, raise maxResponseBytes in the client configuration.
3. Verify you are talking to the real KMS API and not a gateway/error interstitial.
4. Keep the limit in place for untrusted networks; only raise it to a value bounded by your threat model.
5. Log the Content-Length header server-side to distinguish genuine large payloads from garbage.

Example fix

// before
client := kms.NewClient(kms.WithMaxResponseBytes(64<<10)) // Decrypt of 100KB ciphertext fails
// after
client := kms.NewClient(kms.WithMaxResponseBytes(1<<20)) // sized to largest legitimate payload

// size the limit before constructing the client
maxPayload := largestLegitimateCiphertextBytes() // measure from your workload
if maxPayload > defaultMaxResponseBytes {
    client = kms.NewClient(kms.WithMaxResponseBytes(maxPayload + slack))
}

if err != nil && strings.Contains(err.Error(), "response exceeds limit") {
    // log body size from server metrics; verify endpoint identity before raising limit
    return fmt.Errorf("KMS response suspiciously large; verify endpoint: %w", err)
}

When it happens

Trigger: Encrypt or Decrypt calls where the KMS server returns a body larger than the configured maxResponseBytes: a misbehaving/compromised KMS endpoint, a proxy returning an HTML error page inflated beyond the limit, or a maxResponseBytes configured too small for legitimate large ciphertexts.

Common situations: Pointing the KMS client at a wrong endpoint that streams large HTML pages, extremely large plaintext/ciphertext legitimately exceeding the default cap, or testing against a mock server that ignores size constraints.

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

• ambiguous escaped path sequence
• backslash is not allowed in path
• compat route path rejected
• compat upstream forward_headers
• dot segments are not allowed in path

AI-assisted analysis of JuliusBrussee/caveman@3ee70a1026 (2026-09-20). Data as JSON: /api/errors/6909f9ecc9a07f7b. Report an issue: GitHub.

Appendix: source

Thrown at shared/platform/kms/kms.go:374

	}
	req.Header.Set("content-type", "application/json")
	req.Header.Set("accept", "application/json")
	req.Header.Set("x-auth-token", c.token)
	resp, err := c.httpClient.Do(req)
	if err != nil {
		return fmt.Errorf("kms: %s request failed: %w", operation, err)
	}
	defer resp.Body.Close()
	if resp.StatusCode != http.StatusOK {
		_, _ = io.Copy(io.Discard, io.LimitReader(resp.Body, 32<<10))
		return fmt.Errorf("kms: %s returned HTTP %d", operation, resp.StatusCode)
	}
	data, err := io.ReadAll(io.LimitReader(resp.Body, maxResponseBytes+1))
	if err != nil {
		return fmt.Errorf("kms: read %s response: %w", operation, err)
	}
	if len(data) > maxResponseBytes {
		return fmt.Errorf("kms: %s response exceeds limit", operation)
	}
	if err := json.Unmarshal(data, output); err != nil {
		return fmt.Errorf("kms: decode %s response: %w", operation, err)
	}
	return nil
}

View on GitHub (pinned to 3ee70a1026)