flowable/flowable-engine · error · ActivitiIllegalArgumentException

Provided process definition id is null

Error message

Provided process definition id is null

What it means

TimerJobQueryImpl.processDefinitionId() throws ActivitiIllegalArgumentException when called with a null process definition id. The Flowable/Activiti query API validates required filter arguments eagerly instead of producing a broken SQL query. Passing null means the caller intended to filter by process definition but supplied no value.

Source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/TimerJobQueryImpl.java:84

            throw new ActivitiIllegalArgumentException("Provided job id is null");
        }
        this.id = jobId;
        return this;
    }

    @Override
    public TimerJobQueryImpl processInstanceId(String processInstanceId) {
        if (processInstanceId == null) {
            throw new ActivitiIllegalArgumentException("Provided process instance id is null");
        }
        this.processInstanceId = processInstanceId;
        return this;
    }

    @Override
    public TimerJobQueryImpl processDefinitionId(String processDefinitionId) {
        if (processDefinitionId == null) {
            throw new ActivitiIllegalArgumentException("Provided process definition id is null");
        }
        this.processDefinitionId = processDefinitionId;
        return this;
    }

    @Override
    public TimerJobQueryImpl executionId(String executionId) {
        if (executionId == null) {
            throw new ActivitiIllegalArgumentException("Provided execution id is null");
        }
        this.executionId = executionId;
        return this;
    }

    @Override
    public TimerJobQuery executable() {
        executable = true;
        return this;

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Pass a non-null process definition id, e.g. managementService.createTimerJobQuery().processDefinitionId(actualId)
2. If filtering by definition id is optional, guard the call: only invoke processDefinitionId(id) when id != null
3. Verify the process was deployed and fetch the id via repositoryService.createProcessDefinitionQuery() before querying

Example fix

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

if (processDefinitionId == null || processDefinitionId.isEmpty()) {
    throw new IllegalStateException("processDefinitionId required before querying timer jobs");
}
query.processDefinitionId(processDefinitionId);

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

try {
    query.processDefinitionId(id);
} catch (ActivitiIllegalArgumentException e) {
    log.warn("Null process definition id supplied, skipping filter");
}

When it happens

Trigger: Calling timerJobQuery().processDefinitionId(null) on a TimerJobQuery, typically when the id comes from an uninitialized variable, a failed processDefinitionService lookup, or an optional method parameter that was never set.

Common situations: Variable holding the definition id was never populated because the process was not deployed or the lookup returned null; refactored code dropped a default value; mapping an optional REST request parameter straight into the query builder.

Related errors

• Provided execution id is null
• Provided exception message is null
• Provided date is null
• Provided exception message is null
• Provided tenant id is null

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