flowable/flowable-engine · critical · FlowableException

Failed to determine FlowableHttpClient

Error message

Failed to determine FlowableHttpClient

What it means

HttpClientConfig.determineHttpClient selects a concrete FlowableHttpClient implementation based on which HTTP client dependency is on the classpath (e.g. Apache HttpComponents 5, or older client). If none of the supported client classes can be instantiated/located, it throws FlowableException('Failed to determine FlowableHttpClient'). This normally means no supported HTTP client library was included in the application's dependencies.

Source

Thrown at modules/flowable-http-common/src/main/java/org/flowable/http/common/impl/HttpClientConfig.java:251

    public FlowableHttpClient determineHttpClient() {
        if (httpClient != null) {
            return httpClient;
        } else if (isApacheHttpComponentsPresent) {
            // Backwards compatibility, if apache HTTP Components is present then it has priority
            this.httpClient = new ApacheHttpComponentsFlowableHttpClient(this);
            return this.httpClient;
        } else if (isSpringWebClientPresent && isReactorHttpClientPresent) {
            this.httpClient = new SpringWebClientFlowableHttpClient(this);
            return httpClient;
        } else if (isApacheHttpComponents5Present) {
            ApacheHttpComponents5FlowableHttpClient httpClient = new ApacheHttpComponents5FlowableHttpClient(this);
            this.httpClient = httpClient;
            this.closeRunnable = httpClient::close;
            return this.httpClient;
        }
        else {
            throw new FlowableException("Failed to determine FlowableHttpClient");
        }
    }

    public boolean isDefaultParallelInSameTransaction() {
        return defaultParallelInSameTransaction;
    }

    public void setDefaultParallelInSameTransaction(boolean defaultParallelInSameTransaction) {
        this.defaultParallelInSameTransaction = defaultParallelInSameTransaction;
    }

    public void close() {
        if (closeRunnable != null) {
            closeRunnable.run();
        }
    }
}

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Add the Apache HttpComponents 5 client dependency (flowable module that provides ApacheHttpComponents5FlowableHttpClient) to the classpath
  2. Explicitly set the clientType (setHttpClientType) to a supported value matching the dependency you actually have
  3. Check dependency conflicts: mvn dependency:tree and ensure the expected client JAR is packaged in the deployable artifact
  4. Upgrade/downgrade Flowable modules so config and client implementations are from the same version

Example fix

// before
HttpClientConfig cfg = new HttpClientConfig(); // no client type, no impl on classpath
// after
HttpClientConfig cfg = new HttpClientConfig();
cfg.setHttpClientType("apache-httpcomponents5"); // with matching dependency present
Defensive patterns

Strategy: fallback

Validate before calling

try {
    Class.forName("org.apache.hc.client5.http.classic.HttpClient");
} catch (ClassNotFoundException e) {
    throw new IllegalStateException("Apache HttpComponents 5 client dependency missing from classpath");
}

Try / catch

try {
    HttpClientConfig cfg = new HttpClientConfig();
    HttpClient client = cfg.determineHttpClient();
} catch (FlowableException e) {
    if (e.getMessage().contains("Failed to determine FlowableHttpClient")) {
        throw new IllegalStateException("Add a supported HTTP client dependency (e.g. flowable httpcomponents5)", e);
    }
    throw e;
}

Prevention

When it happens

Trigger: Creating/configuring an HttpClientConfig (via Spring config or the HTTP task engine) where the clientType is unset/unrecognized and no supported Apache HttpComponents client is on the classpath, so all branches fall through to the else throw.

Common situations: Missing flowable-http-client / httpcomponents5 dependency at runtime; excluding the transitive Apache dependency in a shade/assembly jar; mixing Flowable versions where the expected client class changed; using a custom clientType string not handled by the switch.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

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