flowable/flowable-engine · error · FlowableIllegalArgumentException

name is null

Error message

name is null

What it means

AbstractVariableQueryImpl.addVariable is the central funnel for all variable criteria; it throws FlowableIllegalArgumentException("name is null") when the variable name is null. A criterion without a name cannot map to any column, so the library fails fast. It also further restricts null/boolean values to EQUALS/NOT_EQUALS/EXISTS-family operators.

Solutions

1. Null-check the variable name before calling any variableValue* criterion
2. Skip the criterion when the name is absent, or fail earlier with a clear validation error
3. Fix the configuration/metadata source that supplies empty variable names
4. Centralize name resolution in one helper that guarantees non-null input

Example fix

// before
query.scopedVariableValueEquals(nameFromConfig, value, ScopeTypes.PROCESS);
// after
if (nameFromConfig != null) {
    query.scopedVariableValueEquals(nameFromConfig, value, ScopeTypes.PROCESS);
}

Objects.requireNonNull(name, "variable name is required"); query.scopedVariableValueEquals(name, value, scopeType);

boolean validCriterion(String name, Object value) { return name != null && (value != null || isBoolean(value) == false || true); }

try { query.scopedVariableValueEquals(name, value, scopeType); } catch (FlowableIllegalArgumentException e) { throw new BadRequestException("variable name missing: " + e.getMessage()); }

When it happens

Trigger: Calling any scoped variable criterion (scopedVariableValueEquals, scopedVariableValueEqualsIgnoreCase, scopedVariableValueNotEquals, scopedVariableValueNotEqualsIgnoreCase, scopedVariableValueGreaterThan, scopedVariableValueGreaterThanOrEqual, etc.) with a null variable name.

Common situations: Query builders driven by configuration/property maps where the variable name key is missing; refactors that renamed a variable and left the name lookup returning null; framework integrations passing metadata-driven names that may be absent.

Related errors

• Case definition category is null
• Case definition id is null
• Case definition key is null
• value is null
• activatedBefore is null

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

Appendix: source

Thrown at modules/flowable-variable-service/src/main/java/org/flowable/variable/service/impl/AbstractVariableQueryImpl.java:301

    @SuppressWarnings("unchecked")
    protected T variableNotExists(String name, boolean localScope) {
        addVariable(name, null, QueryOperator.NOT_EXISTS, localScope);
        return (T) this;
    }

    @SuppressWarnings("unchecked")
    protected T scopedVariableNotExists(String name, String scopeType) {
        addVariable(name, null, QueryOperator.NOT_EXISTS, scopeType, false);
        return (T) this;
    }

    protected void addVariable(String name, Object value, QueryOperator operator, boolean localScope) {
        this.addVariable(name, value, operator, null, localScope);
    }

    protected void addVariable(String name, Object value, QueryOperator operator, String scopeType, boolean localScope) {
        if (name == null) {
            throw new FlowableIllegalArgumentException("name is null");
        }
        if (value == null || isBoolean(value)) {
            // Null-values and booleans can only be used in EQUALS, NOT_EQUALS, EXISTS and NOT_EXISTS
            switch (operator) {
                case GREATER_THAN:
                    throw new FlowableIllegalArgumentException("Booleans and null cannot be used in 'greater than' condition");
                case LESS_THAN:
                    throw new FlowableIllegalArgumentException("Booleans and null cannot be used in 'less than' condition");
                case GREATER_THAN_OR_EQUAL:
                    throw new FlowableIllegalArgumentException("Booleans and null cannot be used in 'greater than or equal' condition");
                case LESS_THAN_OR_EQUAL:
                    throw new FlowableIllegalArgumentException("Booleans and null cannot be used in 'less than or equal' condition");
                default:
                    break;
            }

            if (operator == QueryOperator.EQUALS_IGNORE_CASE && !(value instanceof String)) {
                throw new FlowableIllegalArgumentException("Only string values can be used with 'equals ignore case' condition");

View on GitHub (pinned to d6d39ce1c6)