apache/cassandra · error · HttpException

HttpException(conn.getResponseCode(), conn.getResponseMessag

Error message

HttpException(conn.getResponseCode(), conn.getResponseMessage())

What it means

In apiCall, the connector performs an HTTP request to the cloud metadata service (EC2/GCE metadata endpoint). If the HTTP response code does not match the expected one (typically 200), it throws HttpException carrying the actual response code and message. This signals that the metadata service responded but not with the anticipated status.

Source

Thrown at src/java/org/apache/cassandra/locator/AbstractCloudMetadataServiceConnector.java:115

        return apiCall(metadataServiceUrl, query, "GET", extraHeaders, 200);
    }

    public String apiCall(String url,
                          String query,
                          String method,
                          Map<String, String> extraHeaders,
                          int expectedResponseCode) throws IOException
    {
        HttpURLConnection conn = null;
        try
        {
            // Populate the region and zone by introspection, fail if 404 on metadata
            conn = (HttpURLConnection) new URL(url + query).openConnection();
            extraHeaders.forEach(conn::setRequestProperty);
            conn.setRequestMethod(method);
            conn.setConnectTimeout(requestTimeoutMs);
            if (conn.getResponseCode() != expectedResponseCode)
                throw new HttpException(conn.getResponseCode(), conn.getResponseMessage());

            // Read the information. I wish I could say (String) conn.getContent() here...
            int cl = conn.getContentLength();

            if (cl == -1)
                return null;

            byte[] b = new byte[cl];
            try (DataInputStream d = new DataInputStream((InputStream) conn.getContent()))
            {
                d.readFully(b);
            }
            return new String(b, UTF_8);
        }
        finally
        {
            if (conn != null)
                conn.disconnect();

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Inspect the response code in the exception to identify 404 vs 4xx/5xx and align the metadata URL/path
For AWS, allow token-based IMDSv2 or set instance metadata options to 'optional'
Verify the instance can reach 169.254.169.254 (or the configured endpoint) with curl
Check that requestTimeoutMs is not causing truncated responses; increase cassandra.metadata_request_timeout
If the endpoint intentionally misses (e.g. zone lookup), handle the null/404 path rather than failing

Example fix

// before (assuming plain GET works)
String zone = connector.apiCall("/latest/meta-data/placement/availability-zone", -1);
// after (guard against unexpected status)
try {
    String zone = connector.apiCall("/latest/meta-data/placement/availability-zone", -1);
} catch (HttpException e) {
    logger.warn("Metadata service returned {} {}", e.code, e.getMessage());
}

Defensive patterns

Strategy: try-catch

Validate before calling

// Probe the metadata endpoint before relying on it
curl -s -o /dev/null -w "%{http_code}" http://169.254.169.254/latest/meta-data/ || echo unreachable

Try / catch

try {
    String value = connector.apiCall(path, HttpURLConnection.HTTP_OK);
} catch (HttpException e) {
    logger.warn("Metadata endpoint returned HTTP {} for {}", e.getResponseCode(), path);
    // fall back to configured defaults
}

Prevention

Verify instance metadata service reachability when provisioning nodes
Keep metadata endpoint paths matching the cloud provider's current API version
Configure IMDSv2 token requirements to allow your access pattern
Monitor for metadata service 5xx and set a sane request timeout

When it happens

Trigger: Calling apiCall (directly or via lookups of region/zone/instance-id) when the metadata URL returns a non-expected status — e.g. 404 for an unsupported metadata path, 401/403 for protected metadata endpoints (IMDSv2 token required), or 5xx from an overloaded metadata service.

Common situations: EC2 instance metadata v2 (IMDSv2) requiring a token while the connector does a plain GET; wrong metadata endpoint version in the URL; metadata service disabled on the instance; proxy/firewall rewriting responses; query path changed by the cloud provider.

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

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/f1a23ee303c861b0. Report an issue: GitHub.