{"record":{"id":"74c7a502c9f29709","repo":"keycloak/keycloak","slug":"error-executing-http-method-builder-getmethod","errorCode":null,"errorMessage":"Error executing http method [{builder.getMethod()}]. Response : {String.valueOf(bytes)}","messagePattern":"Error executing http method \\[(.+?)\\]\\. Response : (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"authz/client/src/main/java/org/keycloak/authorization/client/util/HttpMethod.java","lineNumber":115,"sourceCode":"            int statusCode = statusLine.getStatusCode();\n\n            if(logger.isLoggable(Level.FINE)) {\n                logger.fine( \"Response from server: \" + statusCode + \" / \" + statusLine.getReasonPhrase() +  \" / Body : \" + new String(bytes != null? bytes: new byte[0]));\n            }\n\n            if (statusCode < 200 || statusCode >= 300) {\n                throw new HttpResponseException(\"Unexpected response from server: \" + statusCode + \" / \" + statusLine.getReasonPhrase(), statusCode, statusLine.getReasonPhrase(), bytes);\n            }\n\n            if (bytes == null) {\n                return null;\n            }\n\n            return responseProcessor.process(bytes);\n        } catch (HttpResponseException e) {\n            throw e;\n        } catch (Exception e) {\n            throw new RuntimeException(\"Error executing http method [\" + builder.getMethod() + \"]. Response : \" + String.valueOf(bytes), e);\n        }\n    }\n\n    protected void preExecute(RequestBuilder builder) {\n        for (Map.Entry<String, List<String>> param : params.entrySet()) {\n            for (String value : param.getValue()) {\n                builder.addParameter(param.getKey(), value);\n            }\n        }\n    }\n\n    public HttpMethod<R> authorizationBearer(String bearer) {\n        this.builder.addHeader(\"Authorization\", \"Bearer \" + bearer);\n        return this;\n    }\n\n    public HttpMethodResponse<R> response() {\n        this.response = new HttpMethodResponse(this);","sourceCodeStart":97,"sourceCodeEnd":133,"githubUrl":"https://github.com/keycloak/keycloak/blob/66c7e15a3788de7764f07dd2558275a02770e16d/authz/client/src/main/java/org/keycloak/authorization/client/util/HttpMethod.java#L97-L133","documentation":"This is the generic catch-all RuntimeException thrown by the Keycloak authz client's HttpMethod.execute() when an HTTP call fails for any reason OTHER than a non-2xx HTTP status (those are re-thrown as HttpResponseException at HttpMethod.java:104). It wraps the original Exception and includes the HTTP method (GET/POST/etc.) and the raw response bytes that were read so far. The wrapped cause is the real signal: an IOException means a transport/ connectivity failure, while a non-IO exception from responseProcessor.process(bytes) means the body could not be parsed even though the status was 2xx.","triggerScenarios":"Any authz-client call that hits the token, resource, permission, or entitlement endpoints (e.g. AuthzClient.protection().resource().findAll(), a UMA authorization request, or token obtain/refresh) can surface this. It fires when (a) the server is unreachable, TLS handshake fails, or the socket times out during httpClient.execute(builder.build()), or (b) the server returned a 2xx with a body that the configured responseProcessor (JSON deserializer) cannot parse. Note: a genuine 4xx/5xx from the server is NOT this error — it becomes HttpResponseException and is re-thrown at line 113, never reaching this catch block.","commonSituations":"Wrong/authUrl base in Configuration; Keycloak server down or behind a proxy that returns an HTML error page (which then fails JSON parsing on a 2xx); expired/invalid client secret causing a redirect; SSL/cert issues in JDK truststore; clock skew; load balancer returning a 200 health-check page instead of the expected JSON; version mismatch where the server returns a newer JSON shape than the client can deserialize.","solutions":["Inspect the wrapped exception's cause (e.getCause()) and its type: an IOException or UnknownHostException points to a network/connectivity/URL problem, while a JsonParseException/MismatchedInputException points to an unexpected response body.","Enable FINE logging on org.keycloak.authorization.client.util.HttpMethod to see the actual status line and body logged at line 100, which shows exactly what the server returned.","Verify the Configuration.getAuthServerUrl() is reachable and returns Keycloak JSON (curl the /realms/{realm} endpoint directly).","If the cause is JSON parsing on a 2xx, check for a proxy/gateway intercepting the response or a Keycloak client/server version mismatch.","Check the client's truststore and TLS configuration if the cause is a handshake/SSLException."],"exampleFix":"// before: opaque error with no context\ntry {\n    authzClient.protection().resource().findAll();\n} catch (RuntimeException e) {\n    log.error(\"failed\", e); // 'Error executing http method [GET]. Response : ...'\n}\n\n// after: unwrap the real cause and distinguish transport vs parse failures\ntry {\n    authzClient.protection().resource().findAll();\n} catch (HttpResponseException hre) {\n    // genuine non-2xx from server\n    log.error(\"server returned {} {}\", hre.getStatusCode(), hre.getReasonPhrase());\n} catch (RuntimeException e) {\n    Throwable cause = e.getCause();\n    if (cause instanceof java.io.IOException) {\n        log.error(\"transport failure talking to Keycloak\", cause);\n    } else {\n        log.error(\"unexpected response body, could not parse\", cause);\n    }\n}","handlingStrategy":"try-catch","validationCode":"// Validate reachability before relying on the authz client\njava.net.URL u = new java.net.URL(config.getAuthServerUrl() + \"/realms/\" + config.getRealm());\ntry (java.net.HttpURLConnection c = (java.net.HttpURLConnection) u.openConnection()) {\n    c.setConnectTimeout(2000); c.setRequestMethod(\"GET\");\n    int code = c.getResponseCode();\n    if (code != 200) throw new IllegalStateException(\"Keycloak realm endpoint returned \" + code);\n}","typeGuard":null,"tryCatchPattern":"import org.keycloak.authorization.client.util.HttpResponseException;\ntry {\n    authzClient.protection().resource().findAll();\n} catch (HttpResponseException hre) {\n    // server returned non-2xx: genuine HTTP error\n    handleServerError(hre.getStatusCode(), hre.getReasonPhrase(), hre.getResponse());\n} catch (RuntimeException e) {\n    // this catch sees the 'Error executing http method' wrapper\n    Throwable cause = e.getCause();\n    if (cause instanceof java.io.IOException) {\n        handleTransportFailure(cause); // connectivity/TLS/timeout\n    } else {\n        handleParseFailure(cause); // 2xx body not parseable\n    }\n}","preventionTips":["Always configure sane connect/socket timeouts on the authz client's HttpClient to avoid hangs masquerading as failures.","Distinguish HttpResponseException (real server errors) from the generic RuntimeException wrapper so alerts are routed correctly.","Log the wrapped cause, not just the wrapper message, since the cause carries the actionable detail.","Smoke-test the authServerUrl/realm pair with a plain HTTP call during deployment."],"tags":["network","http","authz-client","json","connectivity"],"backgroundTag":null,"analyzedSha":"66c7e15a3788de7764f07dd2558275a02770e16d","analyzedAt":"2026-08-14T01:36:42.651Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}