Activiti/Activiti · error · ActivitiIllegalArgumentException

Process definition id or key cannot be null

Error message

Process definition id or key cannot be null

What it means

AbstractSetProcessDefinitionStateCmd.findProcessDefinition validates the input of process-definition state commands (suspend/activate process definition). If neither a processDefinitionId nor a processDefinitionKey was supplied, it throws ActivitiIllegalArgumentException with this message. Both identifying parameters are null, so the command cannot target any definition.

Solutions

1. Supply either the process definition id or key: use activateProcessDefinitionById(id)/suspendProcessDefinitionById(id) or the *ByKey variants.
2. Validate the caller's inputs before invoking the runtime service and fail fast with a clear message.
3. If the id comes from a repository lookup (e.g. ProcessDefinitionQuery), confirm that lookup returned a non-null value.
4. If you meant to suspend/activate all definitions of a process instance, use suspendProcessInstanceById instead.

Example fix

// before
runtimeService.suspendProcessDefinitionByKey(null);
// after
String key = processDefinition.getKey(); // must be non-null
if (key == null) throw new IllegalArgumentException("processDefinitionKey required");
runtimeService.suspendProcessDefinitionByKey(key);

// validate before calling the runtime service
if (processDefinitionId == null && processDefinitionKey == null) {
    throw new IllegalArgumentException("Provide processDefinitionId or processDefinitionKey");
}

boolean hasIdentifier(String id, String key) { return id != null || key != null; }

try {
    runtimeService.suspendProcessDefinitionById(id);
} catch (ActivitiIllegalArgumentException e) {
    if (e.getMessage().contains("id or key cannot be null")) {
        // surface input validation problem to caller
    }
    throw e;
}

When it happens

Trigger: Calling runtimeService.activateProcessDefinitionById(null), suspendProcessDefinitionByKey(null), or building SetProcessDefinitionStateCmd without setting id or key — e.g. passing null request parameters through REST or programmatic activation/suspension.

Common situations: REST/body parsing that leaves id and key null (empty request body); code paths that intended to pass a key but the variable was never populated; copy-pasted suspension code where only tenantId/params were set.

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
• Candidate group list is null
• Cannot start process instance by message: message name is…
• dataObjectName is null

AI-assisted analysis of Activiti/Activiti@56435b1a97 (2026-09-09). Data as JSON: /api/errors/9f9e3f2d22d18951. Report an issue: GitHub.

Appendix: source

Thrown at activiti-core/activiti-engine/src/main/java/org/activiti/engine/impl/cmd/AbstractSetProcessDefinitionStateCmd.java:108

        if (executionDate != null) {
            // Process definition state change is delayed
            createTimerForDelayedExecution(commandContext, processDefinitions);
        } else {
            // Process definition state is changed now
            changeProcessDefinitionState(commandContext, processDefinitions);
        }
    }

    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 singletonList(processDefinitionEntity);
        }

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

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

        if (processDefinitionId != null) {
            ProcessDefinitionEntity processDefinitionEntity = processDefinitionManager.findById(processDefinitionId);
            if (processDefinitionEntity == null) {
                throw new ActivitiObjectNotFoundException(
                    "Cannot find process definition for id '" + processDefinitionId + "'",
                    ProcessDefinition.class
                );
            }
            processDefinitionEntities.add(processDefinitionEntity);
        } else {
            ProcessDefinitionQueryImpl query = new ProcessDefinitionQueryImpl(commandContext).processDefinitionKey(
                processDefinitionKey
            );

View on GitHub (pinned to 56435b1a97)