{"record":{"id":"ba2a8e99aa38955d","repo":"flowable/flowable-engine","slug":"http-exception-occurred","errorCode":null,"errorMessage":"HTTP exception occurred","messagePattern":"HTTP exception occurred","errorType":"exception","errorClass":"FlowableException","httpStatus":null,"severity":"error","filePath":"modules/flowable-http-common/src/main/java/org/flowable/http/common/impl/apache/ApacheHttpComponentsFlowableHttpClient.java","lineNumber":464,"sourceCode":"\n    protected class ApacheHttpComponentsExecutableHttpRequest implements ExecutableHttpRequest {\n\n        protected final HttpRequestBase request;\n\n        public ApacheHttpComponentsExecutableHttpRequest(HttpRequestBase request) {\n            this.request = request;\n        }\n\n        @Override\n        public HttpResponse call() {\n            try (CloseableHttpClient httpClient = clientBuilder.build()) {\n\n                try (CloseableHttpResponse response = httpClient.execute(request)) {\n                    return toFlowableHttpResponse(response);\n                }\n\n            } catch (ClientProtocolException ex) {\n                throw new FlowableException(\"HTTP exception occurred\", ex);\n            } catch (IOException ex) {\n                throw new FlowableException(\"IO exception occurred\", ex);\n            }\n        }\n    }\n    \n    /**\n     * A HttpDelete alternative that extends {@link HttpEntityEnclosingRequestBase} to allow DELETE with a request body\n     * \n     * @author ikaakkola\n     */\n    protected static class HttpDeleteWithBody extends HttpEntityEnclosingRequestBase {\n\n        public HttpDeleteWithBody(URI uri) {\n            super();\n            setURI(uri);\n        }\n","sourceCodeStart":446,"sourceCodeEnd":482,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-http-common/src/main/java/org/flowable/http/common/impl/apache/ApacheHttpComponentsFlowableHttpClient.java#L446-L482","documentation":"In `ApacheHttpComponentsFlowableHttpClient.call()`, any `ClientProtocolException` thrown while executing the HTTP request via Apache HttpClient 4.x is wrapped in a generic `FlowableException(\"HTTP exception occurred\", cause)`. It signals the response violated the HTTP protocol (invalid status line, malformed headers, missing content-length mismatch, etc.) rather than a transport/IO problem.","triggerScenarios":"`httpClient.execute(request)` inside `call()` throws `ClientProtocolException` — e.g. server returns a malformed HTTP response, an invalid redirect/location header, or a request fails HTTP protocol validation before transport I/O.","commonSituations":"Talking to a non-HTTP service on the target port; a proxy or API gateway returning corrupted/chunked responses; targets that issue redirect Location headers HttpClient cannot parse; L7 load balancers injecting invalid headers.","solutions":["Inspect the wrapped `cause` (e.g. `ex.getCause()`) in logs — the protocol violation detail is in the chained exception.","Verify the target URL scheme/port actually speaks HTTP(S) (no plain TCP/TLS mismatch, no non-HTTP daemon).","Check for intermediary proxies/gateways mangling the response; bypass or fix them.","If redirects are involved, configure the request/client redirect strategy explicitly to match the server's behavior."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"URI uri = new URI(url); // validate early\nif (!\"http\".equals(uri.getScheme()) && !\"https\".equals(uri.getScheme())) {\n    throw new IllegalArgumentException(\"URL must be http(s): \" + url);\n}","typeGuard":null,"tryCatchPattern":"try {\n    return client.call(requestInfo);\n} catch (FlowableException e) {\n    if (\"HTTP exception occurred\".equals(e.getMessage()) && attempt < maxRetries) {\n        return retryWithBackoff(attempt + 1);\n    }\n    throw e; // inspect e.getCause() for the protocol violation\n}","preventionTips":["Always log the chained cause of FlowableException for protocol details.","Test target endpoints with curl first; malformed HTTP responders are the usual culprit.","Beware of intermediaries (proxies, LBs) rewriting responses."],"tags":["http","protocol","network","http-client"],"backgroundTag":"http-request-failed","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-18T11:17:12.947Z"}