flowable/flowable-engine · error · FlowableIllegalArgumentException

No processDefinitionId, processDefinitionKey nor messageName

Error message

No processDefinitionId, processDefinitionKey nor messageName provided

What it means

startProcessInstance requires the builder to identify the process definition by id or key, or a message name to start by message. If none is set, the engine cannot determine what to start and throws FlowableIllegalArgumentException.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/RuntimeServiceImpl.java:882

    }

    @Override
    public Execution addMultiInstanceExecution(String activityId, String parentExecutionId, Map<String, Object> executionVariables) {
        return commandExecutor.execute(new AddMultiInstanceExecutionCmd(activityId, parentExecutionId, executionVariables));
    }

    @Override
    public void deleteMultiInstanceExecution(String executionId, boolean executionIsCompleted) {
        commandExecutor.execute(new DeleteMultiInstanceExecutionCmd(executionId, executionIsCompleted));
    }

    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 FlowableIllegalArgumentException("No processDefinitionId, processDefinitionKey nor messageName provided");
        }
    }

    public ProcessInstance startProcessInstanceAsync(ProcessInstanceBuilderImpl processInstanceBuilder) {
        if (processInstanceBuilder.getProcessDefinitionId() != null || processInstanceBuilder.getProcessDefinitionKey() != null) {
            return (ProcessInstance) commandExecutor.execute(new StartProcessInstanceAsyncCmd(processInstanceBuilder));
        } else {
            throw new FlowableIllegalArgumentException("No processDefinitionId, processDefinitionKey provided");
        }
    }

    public EventSubscription registerProcessInstanceStartEventSubscription(ProcessInstanceStartEventSubscriptionBuilderImpl builder) {
        return commandExecutor.execute(new RegisterProcessInstanceStartEventSubscriptionCmd(builder));
    }

    public void migrateProcessInstanceStartEventSubscriptionsToProcessDefinitionVersion(ProcessInstanceStartEventSubscriptionModificationBuilderImpl builder) {
        commandExecutor.execute(new ModifyProcessInstanceStartEventSubscriptionCmd(builder));
    }

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Set processDefinitionKey (or processDefinitionId) on the builder: runtimeService.createProcessInstanceBuilder().processDefinitionKey("myProcess")
2. If starting by message, call messageName(...) on the builder
3. Verify the configuration/property feeding the builder is actually populated

Example fix

// before
ProcessInstance pi = runtimeService.startProcessInstance(
    runtimeService.createProcessInstanceBuilder().businessKey(bk));
// after
ProcessInstance pi = runtimeService.startProcessInstance(
    runtimeService.createProcessInstanceBuilder().processDefinitionKey("orderProcess").businessKey(bk));

ProcessInstanceBuilderImpl b = runtimeService.createProcessInstanceBuilder();
if (b.getProcessDefinitionId() == null && b.getProcessDefinitionKey() == null && b.getMessageName() == null) {
    throw new IllegalArgumentException("Provide processDefinitionId, processDefinitionKey or messageName");
}
runtimeService.startProcessInstance(b);

try {
    runtimeService.startProcessInstance(builder);
} catch (FlowableIllegalArgumentException e) {
    log.error("Process start misconfigured: {}", e.getMessage());
    throw new ConfigurationException(e);
}

When it happens

Trigger: Calling RuntimeService.startProcessInstance(builder) with a ProcessInstanceBuilderImpl on which none of processDefinitionId, processDefinitionKey, or messageName was set (e.g. only business key or variables were configured).

Common situations: Conditionally populating the builder where all branches failed; building the builder from config where the deployment key property is missing; typo between key/id fields.

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

• No processDefinitionId, processDefinitionKey provided
• The process instance id is mandatory, but '${processInstance
• RuntimeService cannot be null, Obtain your builder instance
• formInfo is null
• No process instance found for id = '" + processInstanceId +

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