Activiti/Activiti · error · ActivitiIllegalArgumentException

processDefinitionKey and processDefinitionId are null

Error message

processDefinitionKey and processDefinitionId are null

What it means

ProcessDefinitionRetriever.getProcessDefinition requires either a process definition id or key to look up a definition in the deployment cache. If both arguments are null it throws this ActivitiIllegalArgumentException because neither lookup path is possible.

Solutions

1. Ensure at least one of processDefinitionId or processDefinitionKey is set before calling.
2. Validate inputs upstream and return a clear client-side error when both are absent.
3. Provide a configured default processDefinitionKey when requests omit the definition reference.

Example fix

// before
ProcessDefinition pd = retriever.getProcessDefinition(null, null);
// after
if (processDefinitionId == null && processDefinitionKey == null) {
    throw new IllegalArgumentException("Provide processDefinitionId or processDefinitionKey");
}
ProcessDefinition pd = retriever.getProcessDefinition(processDefinitionId, processDefinitionKey);

if (processDefinitionId == null && processDefinitionKey == null) {
    throw new IllegalArgumentException("Either processDefinitionId or processDefinitionKey must be provided");
}

try {
    return retriever.getProcessDefinition(processDefinitionId, processDefinitionKey);
} catch (ActivitiIllegalArgumentException e) {
    if (e.getMessage().contains("processDefinitionKey and processDefinitionId are null")) {
        // surface a client-facing 'missing process definition reference' error
    }
    throw e;
}

When it happens

Trigger: Calling getProcessDefinition(null, null), typically when upstream code resolved neither id nor key from a request or message.

Common situations: Missing processDefinitionId/Key in runtime data or API payloads; deserialization leaving fields null; config not supplying a default definition key.

Related errors

• Cannot find process definition with id
• category is null
• categoryLike is null
• categoryNotEquals is null
• Deployment id is null

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

Appendix: source

Thrown at activiti-core/activiti-engine/src/main/java/org/activiti/engine/impl/util/ProcessDefinitionRetriever.java:36

import org.activiti.engine.ActivitiIllegalArgumentException;
import org.activiti.engine.ActivitiObjectNotFoundException;
import org.activiti.engine.ProcessEngineConfiguration;
import org.activiti.engine.impl.persistence.deploy.DeploymentManager;
import org.activiti.engine.repository.ProcessDefinition;

public class ProcessDefinitionRetriever {

    private String tenantId;
    private DeploymentManager deploymentCache;

    public ProcessDefinitionRetriever(String tenantId, DeploymentManager deploymentCache) {
        this.tenantId = tenantId;
        this.deploymentCache = deploymentCache;
    }

    public ProcessDefinition getProcessDefinition(String processDefinitionId, String processDefinitionKey) {
        if (processDefinitionId == null && processDefinitionKey == null) {
            throw new ActivitiIllegalArgumentException("processDefinitionKey and processDefinitionId are null");
        }

        ProcessDefinition processDefinition = this.getProcessDefinitionByProcessDefinitionId(
            processDefinitionId,
            deploymentCache
        );
        if (processDefinition == null) {
            processDefinition = (processDefinitionKey != null && hasNoTenant(tenantId))
                ? this.getProcessDefinitionByProcessDefinitionKey(processDefinitionKey, deploymentCache)
                : this.getProcessDefinitionByProcessDefinitionKeyAndTenantId(
                    processDefinitionKey,
                    tenantId,
                    deploymentCache
                );
            if (processDefinition == null) {
                throw new ActivitiObjectNotFoundException(
                    "No process definition found for key '" +
                    processDefinitionKey +

View on GitHub (pinned to 56435b1a97)