flowable/flowable-engine · error · FlowableIllegalArgumentException

Unsupported variable query operation:

Error message

Unsupported variable query operation:

What it means

FlowableIllegalArgumentException thrown when a QueryVariable's operation is not EQUALS — the default branch of the switch in addVariables. This historic-variable-instances REST endpoint only supports the EQUALS operation for variable clauses in this version, so any other operation (GREATER_THAN, LIKE, etc.) is rejected as unsupported.

Source

Thrown at modules/flowable-rest/src/main/java/org/flowable/rest/service/api/history/HistoricVariableInstanceBaseResource.java:124

            }

            boolean nameLess = variable.getName() == null;

            Object actualValue = restResponseFactory.getVariableValue(variable);

            // A value-only query is only possible using equals-operator
            if (nameLess) {
                throw new FlowableIllegalArgumentException("Value-only query (without a variable-name) is not supported");
            }

            switch (variable.getVariableOperation()) {

            case EQUALS:
                variableInstanceQuery.variableValueEquals(variable.getName(), actualValue);
                break;

            default:
                throw new FlowableIllegalArgumentException("Unsupported variable query operation: " + variable.getVariableOperation());
            }
        }
    }
}

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Use operation EQUALS only for variables clauses on this endpoint; apply additional filtering (range, like) client-side over the returned pages
  2. Use dedicated scalar query parameters where available instead of the variables array (check the endpoint's documented parameter list)
  3. Upgrade Flowable or patch HistoricVariableInstanceBaseResource to add the needed switch cases if range queries are essential
  4. Validate operation strings against the supported set before sending the request

Example fix

// before
{"variables":[{"name":"amount","value":"100","operation":"GREATER_THAN"}]}
// after
const list = await fetch('/history/historic-variable-instances?variables=' + encodeURIComponent(JSON.stringify([{name:'amount', value:'100', operation:'EQUALS'}]))).then(r => r.json());
// client-side refinement
const result = list.data.filter(v => Number(v.value) > 100);
Defensive patterns

Strategy: validation

Validate before calling

const SUPPORTED = ['EQUALS'];
clauses.forEach(c => { if (!SUPPORTED.includes(c.operation)) throw new Error(`unsupported operation ${c.operation} for historic variable query`); });

Type guard

function isSupportedOperation(op) { return op === 'EQUALS'; }

Try / catch

try { return await queryHistoricVariables(clauses); } catch (e) { if (String(e.message).includes('Unsupported variable query operation')) return queryHistoricVariables(clauses.map(c => ({...c, operation:'EQUALS'}))); throw e; }

Prevention

When it happens

Trigger: GET/POST /history/historic-variable-instances with variables=[{"name":"amount","value":"100","operation":"GREATER_THAN"}] — any operation string other than EQUALS that still deserializes into a valid QueryVariableOperation enum value reaches the default branch and throws.

Common situations: Clients reusing runtime-variable query filters (which support more operations) against the historic endpoint; UIs offering full operator dropdowns for history search; upgrading code from a fork or newer Flowable version where additional operations exist.

Related errors

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