flowable/flowable-engine · error · ActivitiIllegalArgumentException

No processDefinitionId, processDefinitionKey nor…

Error message

No processDefinitionId, processDefinitionKey nor messageName provided

What it means

RuntimeServiceImpl.startProcessInstance() dispatches the ProcessInstanceBuilder, which must specify how to start: by processDefinitionId, processDefinitionKey, or messageName. If none of the three is set on the builder, the method throws ActivitiIllegalArgumentException because there is no way to resolve a process definition.

Solutions

Set at least one of processDefinitionId, processDefinitionKey, or messageName on the builder before calling start().
Validate the driving input (key/id/message) before creating the builder and reject incomplete requests early.
Catch ActivitiIllegalArgumentException around start() and return a descriptive 'missing process identifier' error to the caller.
If input provides multiple identifiers, prefer processDefinitionId, then key, then message, ensuring at least one is applied.

Example fix

// before
runtimeService.createProcessInstanceBuilder()
    .variables(vars)
    .start(); // nothing set

// after
runtimeService.createProcessInstanceBuilder()
    .processDefinitionKey("orderProcess")
    .variables(vars)
    .start();

Defensive patterns

Strategy: validation

Validate before calling

if (processDefinitionId == null && processDefinitionKey == null && messageName == null) {
    throw new IllegalArgumentException("Provide processDefinitionId, processDefinitionKey or messageName");
}
ProcessInstanceBuilder b = runtimeService.createProcessInstanceBuilder();
if (processDefinitionId != null) b.processDefinitionId(processDefinitionId);
else if (processDefinitionKey != null) b.processDefinitionKey(processDefinitionKey);
else b.messageName(messageName);
ProcessInstance pi = b.start();

Try / catch

try {
    builder.start();
} catch (org.activiti.engine.ActivitiIllegalArgumentException e) {
    // report missing process identifier to caller
}

Prevention

Validate the start input (id/key/message) before touching the builder API.
Ensure conditional builder setup always sets at least one identifier.
Prefer processDefinitionKey in config-driven starters and validate config completeness at startup.

When it happens

Trigger: Building via runtimeService.createProcessInstanceBuilder() and calling start() without having called processDefinitionId(...), processDefinitionKey(...), or messageName(...) on the builder — e.g. all three sources were conditional and every one was skipped.

Common situations: Dynamic process starters driven by configuration where the config keys (process key, message) are missing/empty; migrating from startProcessInstanceByKey to the builder API and forgetting to set the key; conditional logic that sets id XOR key XOR message but none when the input is incomplete.

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

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

Appendix: source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/RuntimeServiceImpl.java:525

    @Override
    public List<Event> getProcessInstanceEvents(String processInstanceId) {
        return commandExecutor.execute(new GetProcessInstanceEventsCmd(processInstanceId));
    }

    @Override
    public ProcessInstanceBuilder createProcessInstanceBuilder() {
        return new ProcessInstanceBuilderImpl(this);
    }

    public ProcessInstance startProcessInstance(ProcessInstanceBuilderImpl processInstanceBuilder) {
        if (processInstanceBuilder.getProcessDefinitionId() != null
                || processInstanceBuilder.getProcessDefinitionKey() != null) {
            return commandExecutor.execute(new StartProcessInstanceCmd<ProcessInstance>(processInstanceBuilder));
        } else if (processInstanceBuilder.getMessageName() != null) {
            return commandExecutor.execute(new StartProcessInstanceByMessageCmd(processInstanceBuilder));
        } else {
            throw new ActivitiIllegalArgumentException(
                    "No processDefinitionId, processDefinitionKey nor messageName provided");
        }
    }

}

View on GitHub (pinned to d6d39ce1c6)