flowable/flowable-engine · error · FlowableIllegalStateException

The given execution " + execution.getClass().getName() + "…

Error message

The given execution " + execution.getClass().getName() + " is not of type " + VariableScope.class.getName()

What it means

Thrown as FlowableIllegalStateException when ScriptHttpHandler.handleHttpRequest receives a VariableContainer that is not a VariableScope. The script request handler needs to store the HttpRequest as a transient local variable on the scope so the script can access it, which is only possible on VariableScope instances. Indicates the HTTP handler was invoked with an unsupported execution type.

Solutions

Ensure the execution passed to the HTTP handler is an instance of org.flowable.variable.api.delegate.VariableScope (e.g. DelegateExecution / ExecutionEntity).
If you have custom invocation code, pass the underlying DelegateExecution instead of a wrapper VariableContainer.
Switch from a script HTTP handler to a delegate-expression handler if you cannot guarantee a VariableScope execution.
Check for custom VariableContainer implementations in your integration layer and make them extend VariableScope.

Example fix

// before
VariableContainer container = new MyCustomContainer();
httpHandler.handleHttpRequest(container, request, client);

// after
if (container instanceof VariableScope) {
    httpHandler.handleHttpRequest(container, request, client);
}

Defensive patterns

Strategy: type-guard

Validate before calling

if (!(container instanceof VariableScope)) {
    throw new IllegalArgumentException("HTTP script request handler requires a VariableScope execution");
}

Type guard

boolean isVariableScope(VariableContainer c) {
    return c instanceof org.flowable.variable.api.delegate.VariableScope;
}

Try / catch

try {
    scriptHandler.handleHttpRequest(container, request, client);
} catch (FlowableIllegalStateException e) {
    if (e.getMessage().contains("is not of type")) {
        logger.error("Non-VariableScope execution passed to script HTTP handler: " + e.getMessage());
    } else { throw e; }
}

Prevention

Pass DelegateExecution (a VariableScope) into HTTP handlers, not custom containers.
Avoid plain VariableContainer wrappers in custom HTTP handler invocation code.
Prefer delegate-expression HTTP handlers when execution type cannot be guaranteed.
Test script HTTP handlers with mocks that implement VariableScope.

When it happens

Trigger: A BPMN HTTP task configures a script-based request handler (flowable:script handler for http request), and the engine invokes handleHttpRequest with a VariableContainer implementation that is not a VariableScope.

Common situations: Custom engine extensions or integration code passing a bespoke VariableContainer into the HTTP handler pipeline; using the script handler in a context (e.g. custom job/async executor) that supplies a non-scope container; framework upgrade where handler invocation types changed.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

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

Appendix: source

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

 */
public class ScriptHttpHandler extends AbstractScriptEvaluator implements HttpRequestHandler, HttpResponseHandler {

    public ScriptHttpHandler(Expression language, String script) {
        super(language, script);
    }

    @Override
    protected ScriptingEngines getScriptingEngines() {
        return CommandContextUtil.getProcessEngineConfiguration().getScriptingEngines();
    }

    @Override
    public void handleHttpRequest(VariableContainer execution, HttpRequest httpRequest, FlowableHttpClient client) {
        if (execution instanceof VariableScope) {
            ((VariableScope) execution).setTransientVariableLocal("httpRequest", httpRequest);
            evaluateScriptRequest(createScriptRequest(execution).traceEnhancer(trace -> trace.addTraceTag("type", "httpRequestHandler")));
        } else {
            throw new FlowableIllegalStateException(
                    "The given execution " + execution.getClass().getName() + " is not of type " + VariableScope.class.getName());
        }
    }

    @Override
    public void handleHttpResponse(VariableContainer execution, HttpResponse httpResponse) {
        if (execution instanceof VariableScope) {
            ((VariableScope) execution).setTransientVariableLocal("httpResponse", httpResponse);
            evaluateScriptRequest(createScriptRequest(execution).traceEnhancer(trace -> trace.addTraceTag("type", "httpResponseHandler")));
        } else {
            throw new FlowableIllegalStateException(
                    "The given execution " + execution.getClass().getName() + " is not of type " + VariableScope.class.getName());
        }
    }
}

View on GitHub (pinned to d6d39ce1c6)