flowable/flowable-engine · error · ActivitiIllegalArgumentException

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

ActivitiIllegalArgumentException thrown by addVariable when an EQUALS_IGNORE_CASE condition receives a non-String value. Case-insensitive equality is defined only for strings (the engine lowercases the value), so numbers, dates, booleans (and null, handled earlier) are rejected at query-build time.

Solutions

Convert the value to a String first (String.valueOf(value)) if case-insensitive text matching is intended.
Use plain variableValueEquals for non-string types so type-aware comparison is used.
Validate that filter inputs destined for ignore-case methods are Strings before calling.

Example fix

// before
query.taskVariableValueEqualsIgnoreCase("orderNumber", orderId); // Long
// after
query.taskVariableValueEqualsIgnoreCase("orderNumber", String.valueOf(orderId));

Defensive patterns

Strategy: type-guard

Validate before calling

if (value instanceof String) {
    query.taskVariableValueEqualsIgnoreCase(name, (String) value);
} else if (value != null) {
    query.taskVariableValueEquals(name, value);
}

Type guard

boolean isString(Object o) { return o instanceof String; }

Try / catch

try {
    query.taskVariableValueEqualsIgnoreCase(name, value);
} catch (ActivitiIllegalArgumentException e) {
    log.warn("Ignore-case filter requires a String: {}", e.getMessage());
}

Prevention

Dispatch string values to ignore-case methods and others to plain equals
Convert non-string inputs with String.valueOf only when text matching is intended
Document that *IgnoreCase methods are String-only in query helper APIs

When it happens

Trigger: Calling variableValueEqualsIgnoreCase(name, 42), variableValueEqualsIgnoreCase(name, someDate), or a generic wrapper passing an Object into the ignore-case method.

Common situations: Dynamic query builders accept untyped filter values (JSON numbers, dates parsed from request payloads) and route them into string-only operators; a variable changed from numeric to String and code was 'fixed' by switching to ignore-case matching.

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

Appendix: source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/AbstractVariableQueryImpl.java:188

    private void addVariable(String name, Object value, QueryOperator operator, boolean localScope) {
        if (name == null) {
            throw new ActivitiIllegalArgumentException("name is null");
        }
        if (value == null || isBoolean(value)) {
            // Null-values and booleans can only be used in EQUALS and NOT_EQUALS
            switch (operator) {
                case GREATER_THAN:
                    throw new ActivitiIllegalArgumentException("Booleans and null cannot be used in 'greater than' condition");
                case LESS_THAN:
                    throw new ActivitiIllegalArgumentException("Booleans and null cannot be used in 'less than' condition");
                case GREATER_THAN_OR_EQUAL:
                    throw new ActivitiIllegalArgumentException("Booleans and null cannot be used in 'greater than or equal' condition");
                case LESS_THAN_OR_EQUAL:
                    throw new ActivitiIllegalArgumentException("Booleans and null cannot be used in 'less than or equal' condition");
            }

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

            if (operator == QueryOperator.NOT_EQUALS_IGNORE_CASE && !(value instanceof String)) {
                throw new ActivitiIllegalArgumentException("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 ActivitiIllegalArgumentException("Only string values can be used with 'like' condition");
            }
        }
        queryVariableValues.add(new QueryVariableValue(name, value, operator, localScope));
    }

    private boolean isBoolean(Object value) {
        if (value == null) {
            return false;
        }
        return Boolean.class.isAssignableFrom(value.getClass()) || boolean.class.isAssignableFrom(value.getClass());

View on GitHub (pinned to d6d39ce1c6)