flowable/flowable-engine · error · FlowableIllegalArgumentException

Only string variable values are supported when ignoring…

Error message

Only string variable values are supported when ignoring casing, but was: " + actualValue.getClass().getName()

What it means

Flowable's REST process-instance query API throws this FlowableIllegalArgumentException when a variable filter uses the EQUALS_IGNORE_CASE operation but the supplied variable value is not a String. Case-insensitive equality is only defined for text values, so any other type (Integer, Boolean, Date, serialized object) is rejected before the query is built.

Solutions

Pass the variable value as a JSON string (e.g. "100" not 100) when using EQUALS_IGNORE_CASE
Use the plain EQUALS operation if the value is not a string; it accepts any variable type
Do the case-insensitive comparison client-side by querying with EQUALS on a known type and filtering results in your own code

Example fix

// before
{"name":"status","value":2,"operation":"equalsIgnoreCase"}
// after
{"name":"status","value":"2","operation":"equalsIgnoreCase"}

Defensive patterns

Strategy: validation

Validate before calling

if (typeof value !== 'string') throw new Error('equalsIgnoreCase requires a string variable value, got: ' + typeof value);

Type guard

function isString(v) { return typeof v === 'string'; }

Try / catch

try { await flowable.queryProcessInstances(query); } catch (e) { if (e.constructor.name === 'FlowableIllegalArgumentException' && e.message.includes('ignoring casing')) { /* coerce value to string or switch to EQUALS */ } else { throw e; } }

Prevention

Only use *_IGNORE_CASE operations for text variables
Keep a mapping of operation -> allowed value types in your client
Quote numeric values as strings when pattern/ignore-case matching

When it happens

Trigger: Calling GET/POST on the process-instance query endpoint (e.g. /runtime/process-instances) with a variableQuery where variableOperation=EQUALS_IGNORE_CASE and the variable value is a non-string JSON value such as a number or boolean.

Common situations: Sending {"name":"amount","value":100,"operation":"equalsIgnoreCase"} instead of a quoted string; client generators that auto-serialize numbers; copying a query that used 'equals' (any type allowed) and switching the operation without changing the value type.

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/992a13fad4abe32b. Report an issue: GitHub.

Appendix: source

Thrown at modules/flowable-rest/src/main/java/org/flowable/rest/service/api/runtime/process/BaseProcessInstanceResource.java:312

            if (nameLess && variable.getVariableOperation() != QueryVariableOperation.EQUALS) {
                throw new FlowableIllegalArgumentException("Value-only query (without a variable-name) is only supported when using 'equals' operation.");
            }

            switch (variable.getVariableOperation()) {

            case EQUALS:
                if (nameLess) {
                    processInstanceQuery.variableValueEquals(actualValue);
                } else {
                    processInstanceQuery.variableValueEquals(variable.getName(), actualValue);
                }
                break;

            case EQUALS_IGNORE_CASE:
                if (actualValue instanceof String) {
                    processInstanceQuery.variableValueEqualsIgnoreCase(variable.getName(), (String) actualValue);
                } else {
                    throw new FlowableIllegalArgumentException("Only string variable values are supported when ignoring casing, but was: " + actualValue.getClass().getName());
                }
                break;

            case NOT_EQUALS:
                processInstanceQuery.variableValueNotEquals(variable.getName(), actualValue);
                break;

            case NOT_EQUALS_IGNORE_CASE:
                if (actualValue instanceof String) {
                    processInstanceQuery.variableValueNotEqualsIgnoreCase(variable.getName(), (String) actualValue);
                } else {
                    throw new FlowableIllegalArgumentException("Only string variable values are supported when ignoring casing, but was: " + actualValue.getClass().getName());
                }
                break;

            case LIKE:
                if (actualValue instanceof String) {
                    processInstanceQuery.variableValueLike(variable.getName(), (String) actualValue);

View on GitHub (pinned to d6d39ce1c6)