What causes "Unsupported variable query operation: ${friendlyName}" in flowable/flowable-engine?

flowable/flowable-engine · error · FlowableIllegalArgumentException

Unsupported variable query operation: ${friendlyName}

Error message

Unsupported variable query operation: ${friendlyName}

What it means

QueryVariable.QueryVariableOperation maps friendly operation names (equals, notEquals, like, etc.) used in variable query REST payloads to enum values. forFriendlyName throws FlowableIllegalArgumentException when the supplied string matches no enum constant.

Source

Thrown at modules/flowable-cmmn-rest/src/main/java/org/flowable/cmmn/rest/service/api/engine/variable/QueryVariable.java:94

                "greaterThanOrEquals"), LESS_THAN("lessThan"), LESS_THAN_OR_EQUALS("lessThanOrEquals"), EXISTS("exists"), NOT_EXISTS("notExists");

        private final String friendlyName;

        private QueryVariableOperation(String friendlyName) {
            this.friendlyName = friendlyName;
        }

        public String getFriendlyName() {
            return friendlyName;
        }

        public static QueryVariableOperation forFriendlyName(String friendlyName) {
            for (QueryVariableOperation type : values()) {
                if (type.friendlyName.equals(friendlyName)) {
                    return type;
                }
            }
            throw new FlowableIllegalArgumentException("Unsupported variable query operation: " + friendlyName);
        }
    }

}

View on GitHub (pinned to d6d39ce1c6)

Solutions

Use an exact supported operation name (e.g. equals, notEquals, greaterThan, greaterThanOrEquals, lessThan, lessThanOrEquals, like, in)
Trim/normalize the operation string client-side before sending
Check the Flowable version's QueryVariable enum for available operations when upgrading/downgrading
Update client code or an API mapping layer to translate operator names

Example fix

// before
{"name":"priority","operation":"eq","value":10}
// after
{"name":"priority","operation":"equals","value":10}

Defensive patterns

Strategy: validation

Validate before calling

Set<String> ops = Set.of("equals","notEquals","greaterThan","greaterThanOrEquals","lessThan","lessThanOrEquals","like","in");
if (!ops.contains(operation)) throw new IllegalArgumentException("unsupported operation: " + operation);

Try / catch

try {
    QueryVariable.QueryVariableOperation op = QueryVariable.QueryVariableOperation.forFriendlyName(operation);
} catch (FlowableIllegalArgumentException e) {
    op = QueryVariable.QueryVariableOperation.EQUALS;
}

Prevention

Map client-side operator enums to Flowable friendly names in one adapter
Never trust raw user input as the operation string
Check the enum in your exact Flowable version before adding new operations

When it happens

Trigger: Sending a task/case variable query filter whose "operation" field is not one of the supported friendly names (e.g. "eq", "greater", "==" instead of "equals", "greaterThan").

Common situations: Porting clients from other REST APIs with different operator naming; case/whitespace mismatches; new operations used against an older Flowable version that lacks them.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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