flowable/flowable-engine · error · IllegalArgumentException

This map does not support 'null' keys.

Error message

This map does not support 'null' keys.

What it means

ProcessVariableMap is a CDI-injected Map view over process variables backed by BusinessProcess. Its get(Object) method rejects null keys with IllegalArgumentException because a process variable cannot exist without a name; the map contract explicitly does not support null keys. The exception is thrown before any lookup against the process engine happens.

Source

Thrown at modules/flowable-cdi/src/main/java/org/flowable/cdi/impl/ProcessVariableMap.java:38

import org.flowable.cdi.BusinessProcess;

/**
 * Allows to expose the process variables of the current business process as a {@code java.util.Map<String,Object>}.
 * <p>
 * The map delegates changes to {@link BusinessProcess#setVariable(String, Object)} and {@link BusinessProcess#getVariable(String)}, so that they are not flushed prematurely.
 * 
 * @author Daniel Meyer
 */
public class ProcessVariableMap implements Map<String, Object> {

    @Inject
    private BusinessProcess businessProcess;

    @Override
    public Object get(Object key) {
        if (key == null) {
            throw new IllegalArgumentException("This map does not support 'null' keys.");
        }
        return businessProcess.getVariable(key.toString());
    }

    @Override
    public Object put(String key, Object value) {
        if (key == null) {
            throw new IllegalArgumentException("This map does not support 'null' keys.");
        }
        Object variableBefore = businessProcess.getVariable(key);
        businessProcess.setVariable(key, value);
        return variableBefore;
    }

    @Override
    public void putAll(Map<? extends String, ? extends Object> m) {
        for (Map.Entry<? extends String, ? extends Object> newEntry : m.entrySet()) {
            businessProcess.setVariable(newEntry.getKey(), newEntry.getValue());

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Ensure the variable name is non-null before calling get(): check the source of the key (config, parameter) for null.
  2. Wrap the map access in a null check: if (key != null) { map.get(key); }
  3. If the key is legitimately absent, skip the lookup instead of calling get with null.

Example fix

// before
String varName = config.getVariableName();
Object value = processVariableMap.get(varName);

// after
String varName = config.getVariableName();
Object value = varName != null ? processVariableMap.get(varName) : null;
Defensive patterns

Strategy: validation

Validate before calling

if (key == null) { throw new IllegalArgumentException("variable name must not be null"); }
Object value = processVariableMap.get(key);

Type guard

boolean isValidKey(Object key) { return key instanceof String && !((String) key).isEmpty(); }

Try / catch

try { value = processVariableMap.get(key); } catch (IllegalArgumentException e) { value = null; /* null key: skip */ }

Prevention

When it happens

Trigger: Calling ProcessVariableMap.get(null), e.g. via code that dereferences a variable name that is null, or framework code (EL, templating, serialization libraries) that probes the map with a null key.

Common situations: A developer builds the map key from a config property or request parameter that is null/missing; a generic Map-writing helper passes null keys; a library iterating keys assumes null keys are allowed.

Related errors

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