flowable/flowable-engine · error · FlowableIllegalArgumentException

Process definition id is null

Error message

Process definition id is null

What it means

ExecutionQuery.processDefinitionId() requires a non-null process definition id; null would remove the filter, so Flowable throws FlowableIllegalArgumentException. This applies both to normal and OR-statement query building.

Solutions

1. Pass a valid process definition id obtained from ProcessDefinitionQuery/RepositoryService
2. Only call processDefinitionId when the id is non-null; otherwise skip the filter
3. Null-check the result of any singleResult() lookup feeding this method

Example fix

// before
executionQuery.processDefinitionId(definition.getId());
// after
ProcessDefinition definition = repositoryService.createProcessDefinitionQuery()
    .processDefinitionKey(key).latestVersion().singleResult();
if (definition != null) {
    executionQuery.processDefinitionId(definition.getId());
}

if (processDefinitionId == null) { processDefinitionId = resolveDefinitionId(key); }
if (processDefinitionId != null) { query.processDefinitionId(processDefinitionId); }

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

try {
    query.processDefinitionId(id);
} catch (FlowableIllegalArgumentException e) {
    // query without the definition filter or report missing id
}

When it happens

Trigger: Calling executionQuery.processDefinitionId(null), typically when the id comes from a variable that was never initialized, a nullable runtime context, or a failed definition lookup.

Common situations: Tracing executions of a process whose id wasn't resolved from a ProcessInstance; passing a result of singleResult() that was null; missing request parameter.

Related errors

• Process definition key is null
• activatedBefore is null
• activity tenant id is null
• activity tenant id is null
• after time is null

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/ExecutionQueryImpl.java:143

    public ExecutionQueryImpl(CommandContext commandContext, ProcessEngineConfigurationImpl processEngineConfiguration) {
        super(commandContext, processEngineConfiguration.getVariableServiceConfiguration());
        this.processEngineConfiguration = processEngineConfiguration;
    }

    public ExecutionQueryImpl(CommandExecutor commandExecutor, ProcessEngineConfigurationImpl processEngineConfiguration) {
        super(commandExecutor, processEngineConfiguration.getVariableServiceConfiguration());
        this.processEngineConfiguration = processEngineConfiguration;
    }

    public boolean isProcessInstancesOnly() {
        return false; // see dynamic query
    }

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

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

View on GitHub (pinned to d6d39ce1c6)