flowable/flowable-engine · error · FlowableIllegalArgumentException

Only string values can be used with 'equals ignore case'…

Error message

Only string values can be used with 'equals ignore case' condition

What it means

Flowable's EQUALS_IGNORE_CASE comparison only makes sense for string variables; when a non-String value is supplied, addVariable throws this FlowableIllegalArgumentException. Case-insensitive equality is implemented as a SQL lower() comparison, which is only meaningful for text values. The error surfaces at query-construction time.

Solutions

Convert the value to String first (String.valueOf(...)) or use a dedicated string variable
Use plain variableValueEquals for non-string types
Validate value instanceof String before invoking the ignore-case setter
Normalize case in application code and use equals if the value is not a string

Example fix

// before
q.variableValueEqualsIgnoreCase("level", 3);
// after
q.variableValueEqualsIgnoreCase("level", String.valueOf(3)); // or variableValueEquals for numbers

Defensive patterns

Strategy: type-guard

Validate before calling

if (!(value instanceof String)) {
    throw new IllegalArgumentException("equalsIgnoreCase requires a String value");
}
query.variableValueEqualsIgnoreCase(name, (String) value);

Type guard

static boolean isString(Object v) {
    return v instanceof String;
}

Try / catch

try {
    query.variableValueEqualsIgnoreCase(name, value);
} catch (org.flowable.common.engine.api.FlowableIllegalArgumentException e) {
    query.variableValueEquals(name, value);
}

Prevention

Only use ignore-case variants for string variables
Convert non-strings explicitly with String.valueOf when intended
Avoid blind find/replace of equals to equalsIgnoreCase
Note variable types next to their names in code

When it happens

Trigger: Calling variableValueEqualsIgnoreCase / scopedVariableValueEqualsIgnoreCase with an Integer, Boolean, Date or null value, e.g. taskVariableValueEqualsIgnoreCase("priority", 5).

Common situations: Assuming ignore-case variants are drop-in replacements for equals; value typed as Object from generic code; locale-driven code paths passing non-string inputs.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

Thrown at modules/flowable-variable-service/src/main/java/org/flowable/variable/service/impl/AbstractVariableQueryImpl.java:319

            throw new FlowableIllegalArgumentException("name is null");
        }
        if (value == null || isBoolean(value)) {
            // Null-values and booleans can only be used in EQUALS, NOT_EQUALS, EXISTS and NOT_EXISTS
            switch (operator) {
                case GREATER_THAN:
                    throw new FlowableIllegalArgumentException("Booleans and null cannot be used in 'greater than' condition");
                case LESS_THAN:
                    throw new FlowableIllegalArgumentException("Booleans and null cannot be used in 'less than' condition");
                case GREATER_THAN_OR_EQUAL:
                    throw new FlowableIllegalArgumentException("Booleans and null cannot be used in 'greater than or equal' condition");
                case LESS_THAN_OR_EQUAL:
                    throw new FlowableIllegalArgumentException("Booleans and null cannot be used in 'less than or equal' condition");
                default:
                    break;
            }

            if (operator == QueryOperator.EQUALS_IGNORE_CASE && !(value instanceof String)) {
                throw new FlowableIllegalArgumentException("Only string values can be used with 'equals ignore case' condition");
            }

            if (operator == QueryOperator.NOT_EQUALS_IGNORE_CASE && !(value instanceof String)) {
                throw new FlowableIllegalArgumentException("Only string values can be used with 'not equals ignore case' condition");
            }

            if ((operator == QueryOperator.LIKE || operator == QueryOperator.LIKE_IGNORE_CASE) && !(value instanceof String)) {
                throw new FlowableIllegalArgumentException("Only string values can be used with 'like' condition");
            }
        }

        queryVariableValues.add(new QueryVariableValue(name, value, operator, localScope, scopeType));
    }

    protected boolean isBoolean(Object value) {
        if (value == null) {
            return false;
        }

View on GitHub (pinned to d6d39ce1c6)