flowable/flowable-engine · error · FlowableIllegalArgumentException

" + delegateInstance.getClass().getName() + " doesn't…

Error message

" + delegateInstance.getClass().getName() + " doesn't implement " + HttpResponseHandler.class

What it means

ClassDelegateHttpHandler.getHttpResponseHandlerInstance throws this FlowableIllegalArgumentException when the configured HTTP response handler class is instantiated but does not implement the HttpResponseHandler interface. The engine checks the type contract at instantiation time.

Solutions

1. Make the configured class implement HttpResponseHandler (add httpResponse(...)) or point the config at the correct class.
2. Check for swapped arguments: ensure the response-handler className slot doesn't reference the request handler.
3. Verify the import — use the HttpResponseHandler interface from the same Flowable module version as the engine.
4. Add a fast-failing test: instantiate the handler class and assert it instanceof HttpResponseHandler.

Example fix

// before
httpHandlerConfig.setResponseHandlerClassName(MyRequestHandler.class.getName());

// after
httpHandlerConfig.setResponseHandlerClassName(MyResponseHandler.class.getName());

Class<?> c = Class.forName(configuredResponseHandlerClass);
if (!HttpResponseHandler.class.isAssignableFrom(c)) {
    throw new IllegalStateException(configuredResponseHandlerClass + " must implement HttpResponseHandler");
}

static boolean isResponseHandler(String className) throws ClassNotFoundException {
    return HttpResponseHandler.class.isAssignableFrom(Class.forName(className));
}

try {
    handler.getHttpResponseHandlerInstance();
} catch (FlowableIllegalArgumentException e) {
    if (e.getMessage().contains("doesn't implement")) {
        // fall back to default response handling
    }
}

When it happens

Trigger: HTTP activity configuration points HttpResponseHandler handling at a class that doesn't implement org.flowable.http.HttpResponseHandler (e.g. a request handler class or an unrelated delegate); the handler instance is lazily created when a response handler is first needed.

Common situations: Request/response handler classes swapped in configuration; class implements HttpRequestHandler only; stale config after interface rename across Flowable versions; annotation/bean wiring passing the wrong class reference to ClassDelegateHttpHandler's constructor.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

• " + delegateInstance.getClass().getName() + " doesn't…
• doesn't implement CustomPropertiesResolver
• doesn't implement FlowableCollectionHandler
• doesn't implement JavaDelegate, FutureJavaDelegate nor…
• doesn't implement TaskListener

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/bpmn/http/handler/ClassDelegateHttpHandler.java:76

        HttpResponseHandler httpResponseHandler = getHttpResponseHandlerInstance();
        CommandContextUtil.getProcessEngineConfiguration().getDelegateInterceptor().handleInvocation(new HttpResponseHandlerInvocation(httpResponseHandler, execution, httpResponse));
    }

    protected HttpRequestHandler getHttpRequestHandlerInstance() {
        Object delegateInstance = instantiateDelegate(className, fieldDeclarations);
        if (delegateInstance instanceof HttpRequestHandler) {
            return (HttpRequestHandler) delegateInstance;
        } else {
            throw new FlowableIllegalArgumentException(delegateInstance.getClass().getName() + " doesn't implement " + HttpRequestHandler.class);
        }
    }

    protected HttpResponseHandler getHttpResponseHandlerInstance() {
        Object delegateInstance = instantiateDelegate(className, fieldDeclarations);
        if (delegateInstance instanceof HttpResponseHandler) {
            return (HttpResponseHandler) delegateInstance;
        } else {
            throw new FlowableIllegalArgumentException(delegateInstance.getClass().getName() + " doesn't implement " + HttpResponseHandler.class);
        }
    }

}

View on GitHub (pinned to d6d39ce1c6)