Activiti/Activiti · error · ActivitiIllegalArgumentException

Process definition id is null

Error message

Process definition id is null

What it means

ProcessInstanceQueryImpl.processDefinitionId() throws ActivitiIllegalArgumentException when the processDefinitionId string is null. The engine requires a concrete definition id to build the query predicate and rejects null up front.

Solutions

1. Guard for null and only add the filter when an id is present
2. Resolve the definition id earlier and verify it is non-null before building the query
3. If null means 'any definition', omit the call instead

Example fix

// before
query.processDefinitionId(params.get("definitionId"));
// after
String definitionId = params.get("definitionId");
if (definitionId != null && !definitionId.isEmpty()) {
    query.processDefinitionId(definitionId);
}

if (processDefinitionId == null || processDefinitionId.isEmpty()) { throw new IllegalArgumentException("processDefinitionId required"); }
query.processDefinitionId(processDefinitionId);

boolean isValidId(String id) { return id != null && !id.trim().isEmpty(); }

try {
    query.processDefinitionId(id);
} catch (ActivitiIllegalArgumentException e) {
    logger.warn("Missing definition id: {}", e.getMessage());
}

When it happens

Trigger: Calling .processDefinitionId(null) on a ProcessInstanceQuery, typically when the id comes from an unset variable, a failed lookup, or an optional request field.

Common situations: Passing the result of a repositoryService call or form field that was empty; wiring REST params without null checks; refactoring where a default id was removed.

Related errors

• Involved user is null
• key is null
• name is null
• Process definition key is null
• Process definition version is null

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

Appendix: source

Thrown at activiti-core/activiti-engine/src/main/java/org/activiti/engine/impl/ProcessInstanceQueryImpl.java:237

    }

    @Override
    public ProcessInstanceQuery processDefinitionVersion(Integer processDefinitionVersion) {
        if (processDefinitionVersion == null) {
            throw new ActivitiIllegalArgumentException("Process definition version is null");
        }

        if (inOrStatement) {
            this.currentOrQueryObject.processDefinitionVersion = processDefinitionVersion;
        } else {
            this.processDefinitionVersion = processDefinitionVersion;
        }
        return this;
    }

    public ProcessInstanceQueryImpl processDefinitionId(String processDefinitionId) {
        if (processDefinitionId == null) {
            throw new ActivitiIllegalArgumentException("Process definition id is null");
        }

        if (inOrStatement) {
            this.currentOrQueryObject.processDefinitionId = processDefinitionId;
        } else {
            this.processDefinitionId = processDefinitionId;
        }
        return this;
    }

    @Override
    public ProcessInstanceQuery processDefinitionIds(Set<String> processDefinitionIds) {
        if (processDefinitionIds == null) {
            throw new ActivitiIllegalArgumentException("Set of process definition ids is null");
        }
        if (processDefinitionIds.isEmpty()) {
            throw new ActivitiIllegalArgumentException("Set of process definition ids is empty");
        }

View on GitHub (pinned to 56435b1a97)