{"record":{"id":"5e4c4872485e7d64","repo":"flowable/flowable-engine","slug":"cannot-trigger-process-task-plan-item-instance-n","errorCode":null,"errorMessage":"Cannot trigger process task plan item instance : no reference id set","messagePattern":"Cannot trigger process task plan item instance : no reference id set","errorType":"exception","errorClass":"FlowableIllegalStateException","httpStatus":null,"severity":"error","filePath":"modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/behavior/impl/ProcessTaskActivityBehavior.java","lineNumber":166,"sourceCode":"            }\n\n        } else {\n            processInstanceService.startProcessInstance(processDefinitionId, processInstanceId, planItemInstanceEntity.getStageInstanceId(),\n                    planItemInstanceEntity.getTenantId(), inParametersMap, businessKey, variableFormVariables, variableFormInfo, variableFormOutcome);\n        }\n\n        if (!blocking) {\n            CommandContextUtil.getAgenda(commandContext).planCompletePlanItemInstanceOperation(planItemInstanceEntity);\n        }\n    }\n\n    @Override\n    public void trigger(CommandContext commandContext, PlanItemInstanceEntity planItemInstance) {\n        if (!PlanItemInstanceState.ACTIVE.equals(planItemInstance.getState())) {\n            throw new FlowableIllegalStateException(\"Can only trigger a plan item that is in the ACTIVE state\");\n        }\n        if (planItemInstance.getReferenceId() == null) {\n            throw new FlowableIllegalStateException(\"Cannot trigger process task plan item instance : no reference id set\");\n        }\n        if (!ReferenceTypes.PLAN_ITEM_CHILD_PROCESS.equals(planItemInstance.getReferenceType())) {\n            throw new FlowableException(\"Cannot trigger process task plan item instance : reference type '\"\n                    + planItemInstance.getReferenceType() + \"' not supported for \" + planItemInstance);\n        }\n\n        // Need to be set before planning the complete operation\n        CmmnEngineConfiguration cmmnEngineConfiguration = CommandContextUtil.getCmmnEngineConfiguration(commandContext);\n        CaseInstanceEntity caseInstance = cmmnEngineConfiguration.getCaseInstanceEntityManager().findById(planItemInstance.getCaseInstanceId());\n        handleOutParameters(planItemInstance, caseInstance, cmmnEngineConfiguration.getProcessInstanceService());\n\n        // Triggering the plan item (as opposed to a regular complete) terminates the process instance\n        CommandContextUtil.getAgenda(commandContext).planCompletePlanItemInstanceOperation(planItemInstance);\n        deleteProcessInstance(commandContext, planItemInstance);\n    }\n\n    @Override\n    public void onStateTransition(CommandContext commandContext, DelegatePlanItemInstance planItemInstance, String transition) {","sourceCodeStart":148,"sourceCodeEnd":184,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/behavior/impl/ProcessTaskActivityBehavior.java#L148-L184","documentation":"When triggering a process task plan item, the engine expects a referenceId pointing at the child process instance it started. A null referenceId means the linkage between the plan item and its child process was never recorded, so Flowable throws FlowableIllegalStateException.","triggerScenarios":"trigger() called on an ACTIVE process-task plan item whose referenceId column is null — e.g. the plan item never actually started a child process (startup failed silently or state manipulated manually), or a non-process task handler routes to this behavior.","commonSituations":"Triggering the wrong plan item by id (a plan item that is not backed by a child process); data corruption or manual DB edits clearing REFERENCE_ID_; custom code that completes plan items without the engine having started the child process.","solutions":["Verify you are triggering the correct plan item instance — query it and confirm referenceType is PLAN_ITEM_CHILD_PROCESS and referenceId is set","Do not trigger process task plan items directly; let the child process completion drive the trigger, or use the correct API for manually completing enabled/human tasks","If data corruption is suspected, inspect ACT_CMMN_RU_PLAN_ITEM_INST.REFERENCE_ID_ for the offending row and restore proper engine-driven execution (restart case if needed)","Audit custom code paths that manipulate plan item state outside the engine API"],"exampleFix":"// before\nruntimeService.completePlanItemInstance(processTaskPlanItemId); // wrong: no child process behind it\n// after\nPlanItemInstance pii = runtimeService.createPlanItemInstanceQuery().planItemInstanceId(processTaskPlanItemId).singleResult();\nif (pii != null && pii.getReferenceId() != null) {\n    runtimeService.completePlanItemInstance(processTaskPlanItemId);\n}","handlingStrategy":"type-guard","validationCode":"PlanItemInstance pii = runtimeService.createPlanItemInstanceQuery()\n    .planItemInstanceId(id).singleResult();\nboolean safe = pii != null && pii.getReferenceId() != null;","typeGuard":"function hasChildProcessRef(pii) { return pii.getReferenceId() != null && 'planItemChildProcess'.equalsIgnoreCase(pii.getReferenceType()); }","tryCatchPattern":"try {\n    // trigger path\n} catch (FlowableIllegalStateException e) {\n    if (e.getMessage().contains(\"no reference id set\")) {\n        // wrong plan item or broken linkage; inspect ACT_CMMN_RU_PLAN_ITEM_INST\n    }\n}","preventionTips":["Only trigger plan items known to be backed by a child process","Never edit plan item rows directly in the DB","Let child-process completion drive triggers","Log referenceId/referenceType in custom listeners"],"tags":["cmmn","plan-item","reference-id","illegal-state"],"backgroundTag":"internal-invariant-violation","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}