flowable/flowable-engine · error · FlowableIllegalArgumentException

Provided case instance id is null

Error message

Provided case instance id is null

What it means

This FlowableIllegalArgumentException is thrown by SuspendedJobQueryImpl.caseInstanceId() when the caller passes a null case instance id. The method delegates to scopeId() with the id and sets the scope type to CMMN; the id null-check fires first. This fail-fast validation prevents building a query with an invalid CMMN scope filter.

Source

Thrown at modules/flowable-job-service/src/main/java/org/flowable/job/service/impl/SuspendedJobQueryImpl.java:327

    }
    
    @Override
    public SuspendedJobQueryImpl scopeDefinitionId(String scopeDefinitionId) {
        if (scopeDefinitionId == null) {
            throw new FlowableIllegalArgumentException("Provided scope definitionid is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.scopeDefinitionId = scopeDefinitionId;
        } else {
            this.scopeDefinitionId = scopeDefinitionId;
        }
        return this;
    }
    
    @Override
    public SuspendedJobQueryImpl caseInstanceId(String caseInstanceId) {
        if (caseInstanceId == null) {
            throw new FlowableIllegalArgumentException("Provided case instance id is null");
        }
        scopeId(caseInstanceId);
        scopeType(ScopeTypes.CMMN);
        return this;
    }
    
    @Override
    public SuspendedJobQueryImpl caseDefinitionId(String caseDefinitionId) {
        if (caseDefinitionId == null) {
            throw new FlowableIllegalArgumentException("Provided case definition id is null");
        }
        scopeDefinitionId(caseDefinitionId);
        scopeType(ScopeTypes.CMMN);
        return this;
    }

    @Override
    public SuspendedJobQueryImpl caseDefinitionKey(String caseDefinitionKey) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Check CaseInstance/lookup results for null before querying by id
2. Only call caseInstanceId() when a valid id is available; otherwise use an unfiltered or different query
3. Fix upstream resolution logic to handle 'not found' explicitly
4. Validate request parameters before mapping to the query

Example fix

// before
CaseInstance ci = runtimeService.createCaseInstanceQuery().caseInstanceBusinessKey(bk).singleResult();
query.caseInstanceId(ci.getId()); // NPE risk / null id
// after
CaseInstance ci = runtimeService.createCaseInstanceQuery().caseInstanceBusinessKey(bk).singleResult();
if (ci != null) {
    query.caseInstanceId(ci.getId());
}

if (caseInstanceId != null) {
    query.caseInstanceId(caseInstanceId);
}

boolean hasCaseInstanceId = caseInstanceId != null && !caseInstanceId.isBlank();

try {
    query.caseInstanceId(caseInstanceId);
} catch (FlowableIllegalArgumentException e) {
    if (e.getMessage().contains("case instance id is null")) {
        // handle absence of case instance explicitly (log, skip, or alternate query)
    } else {
        throw e;
    }
}

When it happens

Trigger: Calling suspendedJobQuery().caseInstanceId(null), typically when the case instance was not found, an optional path/parameter was absent, or a lookup returned null.

Common situations: Chaining from a CaseInstance variable that is null (instance not started or already completed); REST handlers passing missing query params; batch jobs iterating over possibly-absent case references.

Related errors

• Provided scope id is null
• Provided sub scope 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/35615a21a2be0e8b. Report an issue: GitHub.