flowable/flowable-engine · error · FlowableIllegalArgumentException

Provided scope id is null

Error message

Provided scope id is null

What it means

JobQueryImpl.scopeId(String) throws FlowableIllegalArgumentException when the scope id is null. Scope ids identify scopes such as cases or processes (also used internally by caseInstanceId(), which delegates here), and null is rejected at query construction. Flowable validates every filter argument eagerly so invalid queries fail immediately.

Source

Thrown at modules/flowable-job-service/src/main/java/org/flowable/job/service/impl/JobQueryImpl.java:242

    }

    @Override
    public JobQueryImpl elementName(String elementName) {
        if (elementName == null) {
            throw new FlowableIllegalArgumentException("Provided element name is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.elementName = elementName;
        } else {
            this.elementName = elementName;
        }
        return this;
    }

    @Override
    public JobQueryImpl scopeId(String scopeId) {
        if (scopeId == null) {
            throw new FlowableIllegalArgumentException("Provided scope id is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.scopeId = scopeId;
        } else {
            this.scopeId = scopeId;
        }
        return this;
    }

    @Override
    public JobQuery scopeIds(Collection<String> scopeIds) {
        if (scopeIds == null) {
            throw new FlowableIllegalArgumentException("Provided scope ids are null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.scopeIds = scopeIds;
        } else {
            this.scopeIds = scopeIds;

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Obtain the real scope id from the CaseInstance/Execution (e.g. caseInstance.getId()) before querying
2. Guard the call with a null check and omit the filter when absent
3. If using caseInstanceId(), validate the case id is non-null there; the same error is thrown from scopeId()

Example fix

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

if (scopeId == null) throw new IllegalArgumentException("scopeId must not be null; omit the filter instead");

boolean hasScopeId = scopeId != null && !scopeId.isEmpty();

try {
    query.scopeId(scopeId);
} catch (FlowableIllegalArgumentException e) {
    if (e.getMessage().contains("scope id is null")) {
        // skip filter or rethrow with context
    } else {
        throw e;
    }
}

When it happens

Trigger: Calling scopeId(id) with a null string, or calling caseInstanceId(caseId) with null which routes into scopeId(); also triggered when a scope lookup (case/process instance) returned null.

Common situations: CMMN case handling where the case instance id was never captured; querying jobs after an instance already terminated and its lookup returns null; nullable scope fields mapped from request DTOs.

Related errors

• Provided sub scope id is null
• Provided case instance id is null
• Provided case definition id is null
• Provided case definition key is null
• Deployment id is null

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