flowable/flowable-engine · error · FlowableException

Cannot trigger process task plan item instance : reference t

Error message

Cannot trigger process task plan item instance : reference type '

What it means

The trigger path validates that a process task plan item is backed by a child BPMN process instance via referenceType == PLAN_ITEM_CHILD_PROCESS. Any other reference type (or a mismatched one) makes the trigger invalid, and Flowable throws a FlowableException including the offending reference type.

Source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/behavior/impl/ProcessTaskActivityBehavior.java:169

            processInstanceService.startProcessInstance(processDefinitionId, processInstanceId, planItemInstanceEntity.getStageInstanceId(),
                    planItemInstanceEntity.getTenantId(), inParametersMap, businessKey, variableFormVariables, variableFormInfo, variableFormOutcome);
        }

        if (!blocking) {
            CommandContextUtil.getAgenda(commandContext).planCompletePlanItemInstanceOperation(planItemInstanceEntity);
        }
    }

    @Override
    public void trigger(CommandContext commandContext, PlanItemInstanceEntity planItemInstance) {
        if (!PlanItemInstanceState.ACTIVE.equals(planItemInstance.getState())) {
            throw new FlowableIllegalStateException("Can only trigger a plan item that is in the ACTIVE state");
        }
        if (planItemInstance.getReferenceId() == null) {
            throw new FlowableIllegalStateException("Cannot trigger process task plan item instance : no reference id set");
        }
        if (!ReferenceTypes.PLAN_ITEM_CHILD_PROCESS.equals(planItemInstance.getReferenceType())) {
            throw new FlowableException("Cannot trigger process task plan item instance : reference type '"
                    + planItemInstance.getReferenceType() + "' not supported for " + planItemInstance);
        }

        // Need to be set before planning the complete operation
        CmmnEngineConfiguration cmmnEngineConfiguration = CommandContextUtil.getCmmnEngineConfiguration(commandContext);
        CaseInstanceEntity caseInstance = cmmnEngineConfiguration.getCaseInstanceEntityManager().findById(planItemInstance.getCaseInstanceId());
        handleOutParameters(planItemInstance, caseInstance, cmmnEngineConfiguration.getProcessInstanceService());

        // Triggering the plan item (as opposed to a regular complete) terminates the process instance
        CommandContextUtil.getAgenda(commandContext).planCompletePlanItemInstanceOperation(planItemInstance);
        deleteProcessInstance(commandContext, planItemInstance);
    }

    @Override
    public void onStateTransition(CommandContext commandContext, DelegatePlanItemInstance planItemInstance, String transition) {
        if (PlanItemInstanceState.ACTIVE.equals(planItemInstance.getState())) {
            // The process task plan item will be deleted by the regular TerminatePlanItemOperation
            if (PlanItemTransition.TERMINATE.equals(transition) || PlanItemTransition.EXIT.equals(transition)) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Check planItemInstance.getReferenceType() before triggering and only call process-task trigger logic for PLAN_ITEM_CHILD_PROCESS
2. Route case-task vs process-task completion through the correct behavior/service methods
3. Fix model/code mismatch: if the plan item became a case task, use the case-task trigger path instead
4. Include the plan item definition/type in logs to trace which listener triggers the wrong path

Example fix

// before
processTaskBehavior.trigger(commandContext, planItemInstance); // assumes process task
// after
if (ReferenceTypes.PLAN_ITEM_CHILD_PROCESS.equals(planItemInstance.getReferenceType())) {
    processTaskBehavior.trigger(commandContext, planItemInstance);
} else {
    // route to case-task / generic handling
}

if (!"planItemChildProcess".equals(planItemInstance.getReferenceType())) {
    throw new IllegalArgumentException("Not a process-task plan item: " + planItemInstance.getId());
}

function isProcessTaskChild(pii) { return 'planItemChildProcess'.equalsIgnoreCase(pii.getReferenceType()); }

try {
    processTaskTrigger(planItem);
} catch (FlowableException e) {
    if (e.getMessage().contains("reference type")) {
        // route to the appropriate behavior for the actual reference type
    }
}

When it happens

Trigger: trigger() called on a plan item whose referenceType is not PLAN_ITEM_CHILD_PROCESS — e.g. the plan item references a child case (PLAN_ITEM_CHILD_CASE) or another entity, and process-task completion logic is applied to it by mistake.

Common situations: Shared completion code that triggers plan items of multiple task types; a case model changed from a process task to a case task while old trigger code remained; event/callback listener registered for the wrong plan item definition.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• ${this.getClass()} error: element is not a CaseElement : ${b
• Plan item instance for {eventSubscription} can not be found
• Could not find plan item instance for plan item with definit
• Can only trigger a plan item that is in the ACTIVE state
• Cannot trigger a plan item which activity behavior does not

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