flowable/flowable-engine · error · FlowableIllegalArgumentException

Plan item instance id is null

Error message

Plan item instance id is null

What it means

FlowableIllegalArgumentException thrown in AbstractNeedsPlanItemInstanceCmd.execute when planItemInstanceId is null. The command validates the required id before doing any engine work because a null id cannot identify a plan item instance. Concrete commands (completing plan items with/without forms) inherit this check.

Source

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

    }

    public AbstractNeedsPlanItemInstanceCmd(String planItemInstanceId, Map<String, Object> variables,
            Map<String, Object> formVariables, String formOutcome, FormInfo formInfo,
            Map<String, Object> localVariables, Map<String, Object> transientVariables) {
        
        this.planItemInstanceId = planItemInstanceId;
        this.variables = variables;
        this.formVariables = formVariables;
        this.formOutcome = formOutcome;
        this.formInfo = formInfo;
        this.localVariables = localVariables;
        this.transientVariables = transientVariables;
    }

    @Override
    public Void execute(CommandContext commandContext) {
        if (planItemInstanceId == null) {
            throw new FlowableIllegalArgumentException("Plan item instance id is null");
        }

        CmmnEngineConfiguration cmmnEngineConfiguration = CommandContextUtil.getCmmnEngineConfiguration(commandContext);
        PlanItemInstanceEntity planItemInstanceEntity = cmmnEngineConfiguration.getPlanItemInstanceEntityManager().findById(planItemInstanceId);
        if (planItemInstanceEntity == null) {
            throw new FlowableObjectNotFoundException("Cannot find plan item instance for id " + planItemInstanceId, PlanItemInstanceEntity.class);
        }

        if (formInfo != null) {
            FormService formService = CommandContextUtil.getFormService(commandContext);
            if (formService == null) {
                throw new FlowableIllegalStateException("Form engine is not initialized");
            }

            Map<String, Object> variablesFromFormSubmission = formService.getVariablesFromFormSubmission(planItemInstanceEntity.getPlanItemDefinitionId(), 
                    planItemInstanceEntity.getPlanItemDefinitionType(), planItemInstanceEntity.getCaseInstanceId(), planItemInstanceEntity.getCaseDefinitionId(), 
                    ScopeTypes.CMMN, formInfo, formVariables, formOutcome);

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Validate the planItemInstanceId non-null/non-empty before calling the task service
2. Ensure the UI/API caller always supplies the plan item id obtained from plan item instance queries
3. Check the upstream query that produced the id for null results
4. Use the correct API overload where the id is a required parameter

Example fix

// before
cmmnTaskService.completePlanItemPlanForm(planItemInstanceId, caseInstanceId, formInfo, variables, null);
// after
Objects.requireNonNull(planItemInstanceId, "planItemInstanceId is required");
cmmnTaskService.completePlanItemPlanForm(planItemInstanceId, caseInstanceId, formInfo, variables, null);

if (planItemInstanceId == null || planItemInstanceId.isBlank()) throw new IllegalArgumentException("planItemInstanceId is required");

boolean hasPlanItemInstanceId(String id) { return id != null && !id.isBlank(); }

try { cmmnTaskService.completePlanItemPlanForm(...); }
catch (FlowableIllegalArgumentException e) { log.error("Missing/invalid planItemInstanceId: {}", e.getMessage()); }

When it happens

Trigger: Calling cmmnTaskService methods such as completePlanItemPlanForm or completePlanItemStandaloneForm with a null planItemInstanceId; id variable never set from a previous query; request body missing the plan item id field.

Common situations: REST endpoints where planItemInstanceId came from an optional field that was absent; front-end sent null for an unstarted plan item; code deriving the id from another entity that returned null.

Related errors

• planItemInstanceId is null
• Could not resolve case instance id
• Can only trigger a plan item that is in the ACTIVE state
• Case instance id is null
• Cannot find plan item instance for id ${planItemInstanceId}

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