flowable/flowable-engine · error · ActivitiIllegalArgumentException

Process definition id is null

Error message

Process definition id is null

What it means

ProcessInstanceQueryImpl.processDefinitionId(String) throws ActivitiIllegalArgumentException when the processDefinitionId argument is null. The query API validates filter arguments eagerly, and null is not a valid definition id. Note a non-null but malformed id will instead surface later as an empty result or entity-not-found, so this specific error purely indicates a null argument.

Source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/ProcessInstanceQueryImpl.java:234

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

    @Override
    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 d6d39ce1c6)

Solutions

1. Verify the definition id source is non-null before building the query; fail earlier with a clear message.
2. If the id is unknown, decide explicitly: either resolve it via the repository service or use a different filter (key, key-like).
3. Null-check lookup results from RepositoryService before chaining them into the query.
4. Catch ActivitiIllegalArgumentException and report which required parameter was missing.

Example fix

// before
String defId = findDefinitionId(key, version); // may return null
runtimeService.createProcessInstanceQuery().processDefinitionId(defId);
// after
String defId = findDefinitionId(key, version);
if (defId == null) throw new IllegalStateException("no definition for " + key);
runtimeService.createProcessInstanceQuery().processDefinitionId(defId);

if (processDefinitionId == null) {
    throw new IllegalStateException("process definition id is required");
}
query = query.processDefinitionId(processDefinitionId);

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

try {
    result = query.processDefinitionId(defId).list();
} catch (ActivitiIllegalArgumentException e) {
    if (e.getMessage().contains("Process definition id is null")) {
        throw new BadRequestException("processDefinitionId must not be null");
    }
    throw e;
}

When it happens

Trigger: Calling .processDefinitionId(null) — usually when the id comes from a path/lookup (repositoryService call, request path variable) that resolved to null, or a variable holding the definition was never initialized.

Common situations: Optional lookups (e.g. by key+version) returning null and the result fed straight into the query; null path variables in controllers; beans wired before properties were populated.

Related errors

• process instance tenant id is null
• Process definition category is null
• Process definition name is null
• Process definition version is null
• Set of process definition ids is null

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