flowable/flowable-engine · error · FlowableIllegalArgumentException

Provided process definition id is null

Error message

Provided process definition id is null

What it means

ExternalWorkerJobQuery.processDefinitionId(String) throws FlowableIllegalArgumentException when the provided process definition id is null. Flowable validates query parameters eagerly so null ids never reach the persistence layer. A null definition id is treated as a caller bug, not an empty filter.

Source

Thrown at modules/flowable-job-service/src/main/java/org/flowable/job/service/impl/ExternalWorkerJobQueryImpl.java:149

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

    @Override
    public ExternalWorkerJobQuery 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 ExternalWorkerJobQuery 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)

Solutions

1. Resolve the process definition id via RepositoryService before querying and verify it is non-null.
2. Guard the call site: only call processDefinitionId(id) when id != null.
3. Use processDefinitionKey instead if you filter by key and the id is unavailable (with its own null check).
4. Fix the upstream lookup that returns null (wrong tenant/deployment).

Example fix

// before
query.processDefinitionId(definition.getId());
// after
if (definition != null && definition.getId() != null) {
    query.processDefinitionId(definition.getId());
}

if (definitionId != null && !definitionId.isBlank()) {
    query.processDefinitionId(definitionId);
}

boolean isValidDefinitionId(String id) { return id != null && id.matches("[a-zA-Z0-9_-]+(:[0-9]+)*.*"); }

try {
    query.processDefinitionId(definitionId);
} catch (FlowableIllegalArgumentException e) {
    throw new IllegalArgumentException("processDefinitionId must be provided", e);
}

When it happens

Trigger: Calling externalWorkerJobQuery().processDefinitionId(null), e.g. when the definition id was resolved from a deployment step or repository lookup that failed silently.

Common situations: Monitoring dashboards that filter jobs by definition where the definition is chosen dynamically; migration scripts with missing definition metadata; passing a null from configuration that was not filled in.

Related errors

• category is null
• name is null
• Provided process definition key is null
• categoryLike is null
• categoryNotEquals is null

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