flowable/flowable-engine · error · ActivitiIllegalArgumentException

process instance tenant id is null

Error message

process instance tenant id is null

What it means

ProcessInstanceQueryImpl.processInstanceTenantId(String) throws ActivitiIllegalArgumentException when the tenantId argument is null. The Flowable/Activiti query API validates each filter method's arguments eagerly so that a malformed query fails at construction time rather than producing an unclear SQL error at query execution. A null tenant id is not a legal filter value; to query tenant-less instances there are separate dedicated methods (e.g. processInstanceWithoutTenantId).

Source

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

    @Override
    public ProcessInstanceQuery processInstanceBusinessKey(String businessKey, String processDefinitionKey) {
        if (businessKey == null) {
            throw new ActivitiIllegalArgumentException("Business key is null");
        }
        if (inOrStatement) {
            throw new ActivitiIllegalArgumentException("This method is not supported in an OR statement");
        }

        this.businessKey = businessKey;
        this.processDefinitionKey = processDefinitionKey;
        return this;
    }

    @Override
    public ProcessInstanceQuery processInstanceTenantId(String tenantId) {
        if (tenantId == null) {
            throw new ActivitiIllegalArgumentException("process instance tenant id is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.tenantId = tenantId;
        } else {
            this.tenantId = tenantId;
        }
        return this;
    }

    @Override
    public ProcessInstanceQuery processInstanceTenantIdLike(String tenantIdLike) {
        if (tenantIdLike == null) {
            throw new ActivitiIllegalArgumentException("process instance tenant id is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.tenantIdLike = tenantIdLike;
        } else {
            this.tenantIdLike = tenantIdLike;

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Ensure a non-null tenant id is resolved before building the query; fail fast with your own clear error if it is missing.
2. If you actually want instances with no tenant, call processInstanceWithoutTenantId() instead of passing null.
3. Add a null/empty guard on the source of the tenant id (request header, claim, config) before invoking the query.
4. Wrap query building in ActivitiIllegalArgumentException handling to convert it into an application-level validation error.

Example fix

// before
String tenantId = config.get("tenant");
ProcessInstanceQuery q = runtimeService.createProcessInstanceQuery()
    .processInstanceTenantId(tenantId);
// after
String tenantId = config.get("tenant");
if (tenantId == null) throw new IllegalStateException("tenant id not configured");
ProcessInstanceQuery q = runtimeService.createProcessInstanceQuery()
    .processInstanceTenantId(tenantId);

if (tenantId == null) {
    throw new IllegalStateException("tenantId must be provided before querying process instances");
}

boolean hasTenantId(String tenantId) { return tenantId != null && !tenantId.isEmpty(); }

try {
    runtimeService.createProcessInstanceQuery().processInstanceTenantId(tenantId).list();
} catch (ActivitiIllegalArgumentException e) {
    if (e.getMessage().contains("tenant id is null")) {
        throw new BadRequestException("tenantId is required");
    }
    throw e;
}

When it happens

Trigger: Calling runtimeService.createProcessInstanceQuery().processInstanceTenantId(null) — usually because the tenant id was read from a variable, config, or request parameter that was null/missing.

Common situations: Multi-tenant apps where the tenant is derived from a header, JWT claim, or user record that is absent; passing an Optional/nullable value without unwrapping; refactors that renamed a config key so the lookup now returns null.

Related errors

• Process definition category is null
• Process definition name is null
• Process definition version is null
• Process definition id 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/42c0cfd9cdf855df. Report an issue: GitHub.