flowable/flowable-engine · error · org.flowable.common.engine.api.FlowableIllegalArgumentException

variableValue is null

Error message

variableValue is null

What it means

Flowable throws this when variableValueEquals(name, value) receives a null variableValue. Null is not a legal equality target here because variable value comparisons are done in SQL via typed conversion; to query for variables without a value use a different mechanism rather than passing null. Thrown in HistoricVariableInstanceQueryImpl.variableValueEquals().

Solutions

1. Pass a real value; verify where the null came from.
2. Use Objects.requireNonNull(value) early so failures surface at the right place.
3. If 'no value' is a legitimate filter, filter by variableName and check nullity of results in application code instead.

Example fix

// before
query.variableValueEquals("status", null);

// after
Object status = getConfig("status", "ACTIVE");
query.variableValueEquals("status", status);

Objects.requireNonNull(variableValue, "variableValue must not be null");
query.variableValueEquals(name, variableValue);

boolean hasValue(Object v) { return v != null; }

try {
    query.variableValueEquals(name, value);
} catch (FlowableIllegalArgumentException e) {
    log.warn("Null value passed to variableValueEquals: {}", e.getMessage());
    // skip the filter or supply a default
}

When it happens

Trigger: Calling .variableValueEquals(name, null) — e.g. passing an object that was expected to be initialized, an unboxed wrapper from a cache miss, or a deserialized null.

Common situations: Map.get() returning null for a missing key; optional config values defaulting to null; endpoints forwarding request-supplied values verbatim.

Related errors

• after time is null
• decision tenantId is null
• groupId is null
• identityLinkType is null
• involvedGroups are null

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

Appendix: source

Thrown at modules/flowable-variable-service/src/main/java/org/flowable/variable/service/impl/HistoricVariableInstanceQueryImpl.java:196

        return this;
    }

    @Override
    public HistoricVariableInstanceQuery variableName(String variableName) {
        if (variableName == null) {
            throw new FlowableIllegalArgumentException("variableName is null");
        }
        this.variableName = variableName;
        return this;
    }

    @Override
    public HistoricVariableInstanceQuery variableValueEquals(String variableName, Object variableValue) {
        if (variableName == null) {
            throw new FlowableIllegalArgumentException("variableName is null");
        }
        if (variableValue == null) {
            throw new FlowableIllegalArgumentException("variableValue is null");
        }
        this.variableName = variableName;
        queryVariableValue = new QueryVariableValue(variableName, variableValue, QueryOperator.EQUALS, true);
        return this;
    }

    @Override
    public HistoricVariableInstanceQuery variableValueNotEquals(String variableName, Object variableValue) {
        if (variableName == null) {
            throw new FlowableIllegalArgumentException("variableName is null");
        }
        if (variableValue == null) {
            throw new FlowableIllegalArgumentException("variableValue is null");
        }
        this.variableName = variableName;
        queryVariableValue = new QueryVariableValue(variableName, variableValue, QueryOperator.NOT_EQUALS, true);
        return this;
    }

View on GitHub (pinned to d6d39ce1c6)