flowable/flowable-engine · error · FlowableIllegalArgumentException

No processDefinitionId, processDefinitionKey provided

Error message

No processDefinitionId, processDefinitionKey provided

What it means

startProcessInstanceAsync only supports starting from a process definition (by id or key); unlike the synchronous variant there is no message-based start. If neither id nor key is set on the builder the engine throws FlowableIllegalArgumentException.

Source

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

    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));
    }

    public void deleteProcessInstanceStartEventSubscriptions(ProcessInstanceStartEventSubscriptionDeletionBuilderImpl builder) {
        commandExecutor.execute(new DeleteProcessInstanceStartEventSubscriptionCmd(builder));
    }

    public void changeActivityState(ChangeActivityStateBuilderImpl changeActivityStateBuilder) {
        commandExecutor.execute(new ChangeActivityStateCmd(changeActivityStateBuilder));
    }

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Set processDefinitionKey or processDefinitionId on the builder before calling startProcessInstanceAsync
2. For message starts, use the synchronous startProcessInstance with messageName, or trigger the message via runtimeService.messageEventReceived / startProcessInstanceByMessage
3. Validate builder state before the call

Example fix

// before
ProcessInstance pi = runtimeService.startProcessInstanceAsync(
    runtimeService.createProcessInstanceBuilder().messageName("startMsg"));
// after
ProcessInstance pi = runtimeService.startProcessInstance(
    runtimeService.createProcessInstanceBuilder().messageName("startMsg"));

if (builder.getProcessDefinitionId() == null && builder.getProcessDefinitionKey() == null) {
    throw new IllegalArgumentException("startProcessInstanceAsync requires processDefinitionId or processDefinitionKey");
}
runtimeService.startProcessInstanceAsync(builder);

try {
    runtimeService.startProcessInstanceAsync(builder);
} catch (FlowableIllegalArgumentException e) {
    log.warn("Async start unsupported for this builder; falling back to sync start");
    runtimeService.startProcessInstance(builder);
}

When it happens

Trigger: Calling RuntimeService.startProcessInstanceAsync(builder) with a builder configured only with messageName (or nothing), expecting message-start support like the sync API.

Common situations: Migrating code from startProcessInstance (by message) to async without realizing message starts are unsupported in the async variant; builder fields not populated from config.

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 nor messageName
• 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/df198d7e741b0942. Report an issue: GitHub.