flowable/flowable-engine · error · FlowableIllegalArgumentException

planItemInstanceId is null

Error message

planItemInstanceId is null

What it means

GetLocalVariablesCmd rejects a null planItemInstanceId with FlowableIllegalArgumentException before executing any query. Like the single-variable variant, it is a pre-flight argument validation inside the command. The call never reaches the variable service when the id is missing.

Source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/cmd/GetLocalVariablesCmd.java:44

import org.flowable.variable.service.impl.persistence.entity.VariableInstanceEntity;

/**
 * @author Tijs Rademakers
 */
public class GetLocalVariablesCmd implements Command<Map<String, Object>> {
    
    protected String planItemInstanceId;
    protected Collection<String> variableNames;

    public GetLocalVariablesCmd(String planItemInstanceId, Collection<String> variableNames) {
        this.planItemInstanceId = planItemInstanceId;
        this.variableNames = variableNames;
    }
    
    @Override
    public Map<String, Object> execute(CommandContext commandContext) {
        if (planItemInstanceId == null) {
            throw new FlowableIllegalArgumentException("planItemInstanceId is null");
        }
        
        CmmnEngineConfiguration cmmnEngineConfiguration = CommandContextUtil.getCmmnEngineConfiguration(commandContext);
        List<VariableInstanceEntity> variableInstanceEntities;
        if (variableNames == null || variableNames.isEmpty()) {
            variableInstanceEntities = cmmnEngineConfiguration.getVariableServiceConfiguration().getVariableService()
                    .findVariableInstanceBySubScopeIdAndScopeType(planItemInstanceId, ScopeTypes.CMMN);
        } else {
            variableInstanceEntities = cmmnEngineConfiguration.getVariableServiceConfiguration().getVariableService()
                    .createInternalVariableInstanceQuery()
                    .subScopeId(planItemInstanceId)
                    .scopeType(ScopeTypes.CMMN)
                    .names(variableNames)
                    .list();
        }
        Map<String, Object> variables = new HashMap<>(variableInstanceEntities.size());
        for (VariableInstanceEntity variableInstanceEntity : variableInstanceEntities) {
            variables.put(variableInstanceEntity.getName(), variableInstanceEntity.getValue());

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Resolve and pass a valid plan item instance id before calling.
2. Use Objects.requireNonNull(planItemInstanceId, ...) at the wrapper/service layer for fail-fast behavior.
3. Skip or batch-filter items whose ids resolved to null before querying variables.
4. Fix the upstream resolution that produced the null id.

Example fix

// before
Map<String, Object> vars = cmmnRuntimeService.getLocalVariables(planItemId);
// after
Objects.requireNonNull(planItemId, "planItemInstanceId must not be null");
Map<String, Object> vars = cmmnRuntimeService.getLocalVariables(planItemId);

Objects.requireNonNull(planItemInstanceId, "planItemInstanceId is required");

boolean hasPlanItemId(String id) { return id != null && !id.trim().isEmpty(); }

try {
    vars = cmmnRuntimeService.getLocalVariables(planItemInstanceId);
} catch (FlowableIllegalArgumentException e) {
    log.warn("Missing plan item id for variable read");
    vars = Collections.emptyMap();
}

When it happens

Trigger: Calling cmmnRuntimeService.getLocalVariables(planItemInstanceId) or getLocalVariables(planItemInstanceId, variableNames) with a null id, typically when an upstream lookup returned null or a request payload omitted the id field.

Common situations: REST/DTO mappers leaving the id field unset; scripts iterating items where some ids fail resolution; unit tests constructing commands directly with null ids; Spring expression or script evaluation yielding null.

Related errors

• planItemInstanceId is null
• variableName is null
• planItemInstanceId is null
• caseInstanceId is null
• caseInstanceId is null

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