flowable/flowable-engine · error · FlowableException

Could not start process instance: no externalRef defined for

Error message

Could not start process instance: no externalRef defined for 

What it means

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.

Source

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

    @Override
    public void execute(CommandContext commandContext, PlanItemInstanceEntity planItemInstanceEntity, ChildTaskActivityBehavior.VariableInfo variableInfo) {
        CmmnEngineConfiguration cmmnEngineConfiguration = CommandContextUtil.getCmmnEngineConfiguration(commandContext);
        ProcessInstanceService processInstanceService = cmmnEngineConfiguration.getProcessInstanceService();
        if (processInstanceService == null) {
            throw new FlowableException("Could not start process instance: no " + ProcessInstanceService.class + " implementation found for " + planItemInstanceEntity);
        }

        String externalRef = null;
        if (process != null) {
            externalRef = process.getExternalRef();
        } else if (processRefExpression != null) {
            externalRef = processRefExpression.getValue(planItemInstanceEntity).toString();
        } else if (processRef != null) {
            externalRef = processRef;
        }
        if (StringUtils.isEmpty(externalRef)) {
            throw new FlowableException("Could not start process instance: no externalRef defined for " + planItemInstanceEntity);
        }

        Map<String, Object> inParametersMap = new HashMap<>();
        handleInParameters(planItemInstanceEntity, cmmnEngineConfiguration, inParametersMap, cmmnEngineConfiguration.getExpressionManager());

        FormInfo variableFormInfo = null;
        Map<String, Object> variableFormVariables = null;
        String variableFormOutcome = null;
        if (variableInfo != null) {
            variableFormInfo = variableInfo.formInfo;
            variableFormVariables = variableInfo.formVariables;
            variableFormOutcome = variableInfo.formOutcome;

            if (variableInfo.variables != null && !variableInfo.variables.isEmpty()) {
                inParametersMap.putAll(variableInfo.variables);
            }
        }

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Set a valid externalRef/processRef on the process task in the CMMN model (pointing to an existing BPMN process definition key)
2. If using processRefExpression, ensure the referenced variable is populated before the plan item activates (add it as case variable or via a preceding task)
3. Validate the case model at deployment/design time so empty process refs are caught before runtime
4. Log/inspect the plan item instance id in the message to locate the offending XML element and fix it

Example fix

// before (CMMN XML)
<planItem id="pi1"><planItemDefinition xsi:type="tProcessTask" processRef=""/></planItem>
// after
<planItem id="pi1"><planItemDefinition xsi:type="tProcessTask" processRef="orderProcess"/></planItem>

ProcessTask p = (ProcessTask) planItemDefinition;
String ref = p.getProcessRef();
if (ref == null || ref.trim().isEmpty()) {
    throw new IllegalArgumentException("Process task " + p.getId() + " has empty processRef");
}

try {
    // start case / trigger plan item
} catch (FlowableException e) {
    if (e.getMessage().startsWith("Could not start process instance: no externalRef")) {
        // log plan item id from message; fix model/variable
    }
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Could not start case instance: no case reference defined in
• Could not start process instance: no
• Cannot migrate historic case instances, not enough informati
• Setting variable is not supported for read only delegate exe
• Setting transient variable is not supported for read only de

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