flowable/flowable-engine · error · FlowableIllegalArgumentException

Only string variable values are supported when ignoring casi

Error message

Only string variable values are supported when ignoring casing, but was: {valueClassName}

What it means

Case-insensitive equality on variables is only implemented for string values in the underlying TaskQuery (taskVariableValueEqualsIgnoreCase). If the resolved variable value is not a String (e.g. Integer, Boolean), TaskBaseResource.addTaskvariables throws this FlowableIllegalArgumentException instead of silently coercing.

Source

Thrown at modules/flowable-rest/src/main/java/org/flowable/rest/service/api/runtime/task/TaskBaseResource.java:419

            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) {
                    taskQuery.taskVariableValueEquals(actualValue);
                } else {
                    taskQuery.taskVariableValueEquals(variable.getName(), actualValue);
                }
                break;

            case EQUALS_IGNORE_CASE:
                if (actualValue instanceof String) {
                    taskQuery.taskVariableValueEqualsIgnoreCase(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:
                taskQuery.taskVariableValueNotEquals(variable.getName(), actualValue);
                break;

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

            case GREATER_THAN:
                taskQuery.taskVariableValueGreaterThan(variable.getName(), actualValue);
                break;

View on GitHub (pinned to d6d39ce1c6)

Solutions

Send the value as a JSON string (quote it) if case-insensitive comparison is really intended
Use plain 'equals' for non-string values, which supports all types
Change the variable type stored in the process to a string if case-insensitive search is a requirement

Example fix

// before
{"name":"count","operation":"equalsIgnoreCase","value":5}
// after
{"name":"count","operation":"equals","value":5}

Defensive patterns

Strategy: validation

Validate before calling

function validateIgnoreCaseVar(v) {
  if ((v.operation === 'equalsIgnoreCase') && typeof v.value !== 'string') {
    throw new Error(`equalsIgnoreCase requires a string value, got ${typeof v.value}`);
  }
}

Type guard

const isStringValued = (v) => typeof v.value === 'string';

Try / catch

try {
  const res = await flowable.queryTasks(body);
} catch (e) {
  if (e.message && e.message.includes('ignoring casing')) {
    // switch to 'equals' for non-string values
  } else throw e;
}

Prevention

Use ignore-case operators only for string variables
Do not quote numeric values hoping ignore-case will work — use equals instead
Track variable types in a schema map and pick operators accordingly

When it happens

Trigger: POST/GET /runtime/tasks with a filter {"name":"count","operation":"equalsIgnoreCase","value":5} — the value resolves to an Integer, so the instanceof String check fails.

Common situations: Querying numeric or boolean variables with equalsIgnoreCase; assuming ignoreCase works generically; clients not serializing the value as a JSON string.

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