flowable/flowable-engine · error · FlowableIllegalArgumentException

Variable value is missing for variable: ${name}

Error message

Variable value is missing for variable: ${name}

What it means

This FlowableIllegalArgumentException is thrown by the CMMN REST plan-item-instance query builder when a QueryVariable in the request has no value. The library requires every variable filter to carry both a name and a value (except EXISTS-style operations, which this endpoint does not support). It aborts the query before any query is executed rather than silently dropping the filter.

Source

Thrown at modules/flowable-cmmn-rest/src/main/java/org/flowable/cmmn/rest/service/api/runtime/planitem/PlanItemInstanceBaseResource.java:154

        if (Boolean.TRUE.equals(queryRequest.getWithoutTenantId())) {
            query.planItemInstanceWithoutTenantId();
        }
        
        if (restApiInterceptor != null) {
            restApiInterceptor.accessPlanItemInstanceInfoWithQuery(query, queryRequest);
        }

        return paginateList(requestParams, queryRequest, query, "createTime", allowedSortProperties, restResponseFactory::createPlanItemInstanceResponseList);
    }

    protected void addVariables(PlanItemInstanceQuery planItemInstanceQuery, List<QueryVariable> variables, boolean isCase) {
        for (QueryVariable variable : variables) {
            if (variable.getVariableOperation() == null) {
                throw new FlowableIllegalArgumentException("Variable operation is missing for variable: " + variable.getName());
            }
            if (variable.getValue() == null) {
                throw new FlowableIllegalArgumentException("Variable value is missing for variable: " + variable.getName());
            }

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

            Object actualValue = restResponseFactory.getVariableValue(variable);

            // A value-only query is only possible using equals-operator
            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) {
                    if (isCase) {
                        planItemInstanceQuery.caseVariableValueEquals(actualValue);
                    } else {

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Provide a non-null 'value' for every variable filter in the query request body or URL parameter.
  2. If you intend to filter for existence rather than a concrete value, use an endpoint/query API that supports EXISTS/NOT_EXISTS (e.g. task query), not this plan-item-instance endpoint.
  3. Validate the variable map client-side and remove entries with null values before building the request.
  4. Catch FlowableIllegalArgumentException (HTTP 400) and surface which variable name was missing to the caller.

Example fix

// before
{"name":"orderStatus","variableOperation":"equals","value":null}
// after
{"name":"orderStatus","variableOperation":"equals","value":"open"}
Defensive patterns

Strategy: validation

Validate before calling

if (vars.some(v => v.name == null || v.value == null)) throw new Error("Each variable filter needs name and value");

Type guard

const hasValue = (v) => v != null && typeof v.name === 'string' && v.value != null;

Try / catch

try { const res = await queryPlanItemInstances(body); } catch (e) { if (e.status === 400 && /Variable value is missing/.test(e.message)) { /* fix payload */ } else { throw e; } }

Prevention

When it happens

Trigger: Calling GET/POST on the CMMN plan-item-instance query endpoints (e.g. /cmmn-query/plan-item-instances) with a variable filter whose 'value' field is null or omitted, while 'name' and 'variableOperation' are set.

Common situations: Building the query JSON dynamically from a form or map where the value is an unset/null entry; client-side templating that renders '${name}' into the URL but skips the value; serialization bugs that drop null fields in an inconsistent way.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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