{"record":{"id":"d1523fc0154910f6","repo":"flowable/flowable-engine","slug":"could-not-start-process-instance-no-externalref-d","errorCode":null,"errorMessage":"Could not start process instance: no externalRef defined for ","messagePattern":"Could not start process instance: no externalRef defined for ","errorType":"exception","errorClass":"FlowableException","httpStatus":null,"severity":"error","filePath":"modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/behavior/impl/ProcessTaskActivityBehavior.java","lineNumber":86,"sourceCode":"\n    @Override\n    public void execute(CommandContext commandContext, PlanItemInstanceEntity planItemInstanceEntity, ChildTaskActivityBehavior.VariableInfo variableInfo) {\n        CmmnEngineConfiguration cmmnEngineConfiguration = CommandContextUtil.getCmmnEngineConfiguration(commandContext);\n        ProcessInstanceService processInstanceService = cmmnEngineConfiguration.getProcessInstanceService();\n        if (processInstanceService == null) {\n            throw new FlowableException(\"Could not start process instance: no \" + ProcessInstanceService.class + \" implementation found for \" + planItemInstanceEntity);\n        }\n\n        String externalRef = null;\n        if (process != null) {\n            externalRef = process.getExternalRef();\n        } else if (processRefExpression != null) {\n            externalRef = processRefExpression.getValue(planItemInstanceEntity).toString();\n        } else if (processRef != null) {\n            externalRef = processRef;\n        }\n        if (StringUtils.isEmpty(externalRef)) {\n            throw new FlowableException(\"Could not start process instance: no externalRef defined for \" + planItemInstanceEntity);\n        }\n\n        Map<String, Object> inParametersMap = new HashMap<>();\n        handleInParameters(planItemInstanceEntity, cmmnEngineConfiguration, inParametersMap, cmmnEngineConfiguration.getExpressionManager());\n\n        FormInfo variableFormInfo = null;\n        Map<String, Object> variableFormVariables = null;\n        String variableFormOutcome = null;\n        if (variableInfo != null) {\n            variableFormInfo = variableInfo.formInfo;\n            variableFormVariables = variableInfo.formVariables;\n            variableFormOutcome = variableInfo.formOutcome;\n\n            if (variableInfo.variables != null && !variableInfo.variables.isEmpty()) {\n                inParametersMap.putAll(variableInfo.variables);\n            }\n        }\n","sourceCodeStart":68,"sourceCodeEnd":104,"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#L68-L104","documentation":"A process task plan item resolved to an empty process reference: neither the 'process' element's externalRef, a processRefExpression, nor a processRef attribute yielded a non-empty key, so the engine cannot identify which BPMN process to start. It throws a FlowableException identifying the plan item instance.","triggerScenarios":"execute() runs for a process task whose <flowable:externalRef>/processRef attribute is empty or missing, or whose processRefExpression evaluates to null or empty string on the plan item instance.","commonSituations":"Typos or blanks in the CMMN XML processRef attribute; expression referencing a case variable that is null or empty at activation time; model copied from a template without filling in the referenced process; process model later renamed/deleted so the field was cleared.","solutions":["Set a valid externalRef/processRef on the process task in the CMMN model (pointing to an existing BPMN process definition key)","If using processRefExpression, ensure the referenced variable is populated before the plan item activates (add it as case variable or via a preceding task)","Validate the case model at deployment/design time so empty process refs are caught before runtime","Log/inspect the plan item instance id in the message to locate the offending XML element and fix it"],"exampleFix":"// before (CMMN XML)\n<planItem id=\"pi1\"><planItemDefinition xsi:type=\"tProcessTask\" processRef=\"\"/></planItem>\n// after\n<planItem id=\"pi1\"><planItemDefinition xsi:type=\"tProcessTask\" processRef=\"orderProcess\"/></planItem>","handlingStrategy":"validation","validationCode":"ProcessTask p = (ProcessTask) planItemDefinition;\nString ref = p.getProcessRef();\nif (ref == null || ref.trim().isEmpty()) {\n    throw new IllegalArgumentException(\"Process task \" + p.getId() + \" has empty processRef\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    // start case / trigger plan item\n} catch (FlowableException e) {\n    if (e.getMessage().startsWith(\"Could not start process instance: no externalRef\")) {\n        // log plan item id from message; fix model/variable\n    }\n}","preventionTips":["Validate case models at deployment (empty processRef checks)","Never leave processRef blank in templates","Ensure expression-sourced refs resolve to non-empty values before activation","Add unit tests that activate every process task"],"tags":["cmmn","process-task","missing-required-argument","modeling"],"backgroundTag":"missing-required-argument","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}