flowable/flowable-engine · error · FlowableIllegalArgumentException

Provided process definition id is null

Error message

Provided process definition id is null

What it means

Flowable throws FlowableIllegalArgumentException when SuspendedJobQueryImpl.processDefinitionId() is called with a null argument. Query criteria methods in Flowable validate inputs eagerly so that invalid queries fail at definition time rather than producing broken SQL at execution. Passing null explicitly is never allowed for this criterion.

Solutions

1. Ensure the caller supplies a real process definition id before building the query
2. Skip the processDefinitionId criterion when the value is null instead of calling the method
3. Validate/resolve the id upstream (e.g. check the result of a process definition lookup) before querying

Example fix

// before
List<Job> jobs = managementService.createJobQuery().suspended().processDefinitionId(defId).list();
// after
JobQuery q = managementService.createJobQuery().suspended();
if (defId != null) {
    q = q.processDefinitionId(defId);
}
List<Job> jobs = q.list();

if (processDefinitionId == null) {
    throw new IllegalArgumentException("processDefinitionId must be provided");
}
managementService.createJobQuery().suspended().processDefinitionId(processDefinitionId);

boolean hasProcessDefinitionId = (id != null && !id.isBlank());

When it happens

Trigger: Calling jobQuerySuspensionState...processDefinitionId(null) on a SuspendedJobQuery (e.g. createSuspendedJobQuery().processDefinitionId(variable that is null)).

Common situations: A processDefinitionId variable read from config, a request parameter, or an optional lookup (e.g. repositoryService.createProcessDefinitionQuery().singleResult() returning null) is passed straight into the query without a null check.

Related errors

• Business key is null
• Business status is null
• Case definition category is null
• Case definition id is null
• Case definition ids is null

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

Appendix: source

Thrown at modules/flowable-job-service/src/main/java/org/flowable/job/service/impl/SuspendedJobQueryImpl.java:151

            this.processInstanceId = processInstanceId;
        }
        return this;
    }
    
    @Override
    public SuspendedJobQueryImpl withoutProcessInstanceId() {
        if (inOrStatement) {
            this.currentOrQueryObject.withoutProcessInstanceId = true;
        } else {
            this.withoutProcessInstanceId = true;
        }
        return this;
    }

    @Override
    public SuspendedJobQueryImpl processDefinitionId(String processDefinitionId) {
        if (processDefinitionId == null) {
            throw new FlowableIllegalArgumentException("Provided process definition id is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.processDefinitionId = processDefinitionId;
        } else {
            this.processDefinitionId = processDefinitionId;
        }
        return this;
    }

    @Override
    public SuspendedJobQueryImpl processDefinitionKey(String processDefinitionKey) {
        if (processDefinitionKey == null) {
            throw new FlowableIllegalArgumentException("Provided process definition key is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.processDefinitionKey = processDefinitionKey;
        } else {
            this.processDefinitionKey = processDefinitionKey;

View on GitHub (pinned to d6d39ce1c6)