flowable/flowable-engine · error · FlowableIllegalArgumentException

Process definition id or key cannot be null

Error message

Process definition id or key cannot be null

What it means

findProcessDefinition in AbstractSetProcessDefinitionStateCmd validates that at least one of processDefinitionId or processDefinitionKey was supplied when changing a process definition's state (suspend/activate). If both are null this FlowableIllegalArgumentException is thrown.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/AbstractSetProcessDefinitionStateCmd.java:113

            createTimerForDelayedExecution(commandContext, processDefinitions);
        } else { // Process definition state is changed now
            changeProcessDefinitionState(commandContext, processDefinitions);
        }

        return null;
    }

    protected List<ProcessDefinitionEntity> findProcessDefinition(CommandContext commandContext) {

        // If process definition is already provided (eg. when command is called through the DeployCmd)
        // we don't need to do an extra database fetch and we can simply return it, wrapped in a list
        if (processDefinitionEntity != null) {
            return Collections.singletonList(processDefinitionEntity);
        }

        // Validation of input parameters
        if (processDefinitionId == null && processDefinitionKey == null) {
            throw new FlowableIllegalArgumentException("Process definition id or key cannot be null");
        }

        List<ProcessDefinitionEntity> processDefinitionEntities = new ArrayList<>();
        ProcessDefinitionEntityManager processDefinitionManager = CommandContextUtil.getProcessDefinitionEntityManager(commandContext);

        if (processDefinitionId != null) {

            ProcessDefinitionEntity processDefinitionEntity = processDefinitionManager.findById(processDefinitionId);
            if (processDefinitionEntity == null) {
                throw new FlowableObjectNotFoundException("Cannot find process definition for id '" + processDefinitionId + "'", ProcessDefinition.class);
            }
            processDefinitionEntities.add(processDefinitionEntity);

        } else {

            ProcessDefinitionQueryImpl query = new ProcessDefinitionQueryImpl(commandContext).processDefinitionKey(processDefinitionKey);

            if (tenantId == null || ProcessEngineConfiguration.NO_TENANT_ID.equals(tenantId)) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Set the selector: managementService.activateProcessDefinitionByKey(key) or byId(id)
2. Add a caller-side null check before executing the command
3. Include tenantId with key when using key-based selection in multi-tenant setups

Example fix

// before
SuspendProcessDefinitionBuilder b = managementService.suspendProcessDefinition();
b.suspend(); // no id/key -> throws
// after
managementService.suspendProcessDefinition()
    .processDefinitionKey("orderProcess")
    .suspend();

if (processDefinitionId == null && processDefinitionKey == null) {
    throw new IllegalArgumentException("Provide processDefinitionId or processDefinitionKey");
}

try {
    managementService.suspendProcessDefinition()...;
} catch (FlowableIllegalArgumentException e) {
    // command misconfigured; fix builder wiring
}

When it happens

Trigger: Building a Suspend/ActivateProcessDefinitionCmd (e.g. via managementService.activateProcessDefinitionById/ByKey builders or process definition state commands) without calling either setter, or passing null explicitly.

Common situations: Programmatically built commands where fields are set conditionally and both branches were skipped; copy-paste of command wiring that forgot the selector.

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

• process definition id is null
• process definition id is null
• The process definition version is mandatory, but 'null' has
• Error retrieving app engine info
• No deployment id available

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