flowable/flowable-engine · error · FlowableException

HTTP exception occurred

Error message

HTTP exception occurred

What it means

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.

Solutions

  1. Inspect the wrapped `cause` (e.g. `ex.getCause()`) in logs — the protocol violation detail is in the chained exception.
  2. Verify the target URL scheme/port actually speaks HTTP(S) (no plain TCP/TLS mismatch, no non-HTTP daemon).
  3. Check for intermediary proxies/gateways mangling the response; bypass or fix them.
  4. If redirects are involved, configure the request/client redirect strategy explicitly to match the server's behavior.
Defensive patterns

Strategy: retry

Validate before calling

URI uri = new URI(url); // validate early
if (!"http".equals(uri.getScheme()) && !"https".equals(uri.getScheme())) {
    throw new IllegalArgumentException("URL must be http(s): " + url);
}

Try / catch

try {
    return client.call(requestInfo);
} catch (FlowableException e) {
    if ("HTTP exception occurred".equals(e.getMessage()) && attempt < maxRetries) {
        return retryWithBackoff(attempt + 1);
    }
    throw e; // inspect e.getCause() for the protocol violation
}

Prevention

When it happens

Trigger: `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.

Common situations: 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.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/ba2a8e99aa38955d. Report an issue: GitHub.

Appendix: source

Thrown at modules/flowable-http-common/src/main/java/org/flowable/http/common/impl/apache/ApacheHttpComponentsFlowableHttpClient.java:464

    protected class ApacheHttpComponentsExecutableHttpRequest implements ExecutableHttpRequest {

        protected final HttpRequestBase request;

        public ApacheHttpComponentsExecutableHttpRequest(HttpRequestBase request) {
            this.request = request;
        }

        @Override
        public HttpResponse call() {
            try (CloseableHttpClient httpClient = clientBuilder.build()) {

                try (CloseableHttpResponse response = httpClient.execute(request)) {
                    return toFlowableHttpResponse(response);
                }

            } catch (ClientProtocolException ex) {
                throw new FlowableException("HTTP exception occurred", ex);
            } catch (IOException ex) {
                throw new FlowableException("IO exception occurred", ex);
            }
        }
    }
    
    /**
     * A HttpDelete alternative that extends {@link HttpEntityEnclosingRequestBase} to allow DELETE with a request body
     * 
     * @author ikaakkola
     */
    protected static class HttpDeleteWithBody extends HttpEntityEnclosingRequestBase {

        public HttpDeleteWithBody(URI uri) {
            super();
            setURI(uri);
        }

View on GitHub (pinned to d6d39ce1c6)