flowable/flowable-engine · error · FlowableIllegalArgumentException

Provided case instance id is null

Error message

Provided case instance id is null

What it means

JobQueryImpl.caseInstanceId(String) requires a non-null case instance id and throws FlowableIllegalArgumentException otherwise. Internally it maps the filter to scopeId(caseInstanceId) plus scopeType(ScopeTypes.CMMN); the null check happens before that delegation so the failure is immediate. It is a fail-fast guard against building a CMMN job query without an instance to scope to.

Source

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

    }

    @Override
    public JobQueryImpl 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 JobQueryImpl caseInstanceId(String caseInstanceId) {
        if (caseInstanceId == null) {
            throw new FlowableIllegalArgumentException("Provided case instance id is null");
        }
        scopeId(caseInstanceId);
        scopeType(ScopeTypes.CMMN);
        return this;
    }

    @Override
    public JobQueryImpl caseDefinitionId(String caseDefinitionId) {
        if (caseDefinitionId == null) {
            throw new FlowableIllegalArgumentException("Provided case definition id is null");
        }
        scopeDefinitionId(caseDefinitionId);
        scopeType(ScopeTypes.CMMN);
        return this;
    }

    @Override
    public JobQueryImpl caseDefinitionKey(String caseDefinitionKey) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Check that the case instance exists and the id variable is populated before querying
2. For BPMN jobs use processInstanceId/scopeId with BPMN scope instead of caseInstanceId
3. Skip the caseInstanceId filter when null and use a broader query, then filter in code
4. Null-guard the variable at the call site

Example fix

// before
List<Job> jobs = jobService.createJobQuery().caseInstanceId(caseInstanceId).list();
// after
if (caseInstanceId != null) {
    List<Job> jobs = jobService.createJobQuery().caseInstanceId(caseInstanceId).list();
} else {
    List<Job> jobs = Collections.emptyList();
}

if (caseInstanceId == null) { throw new IllegalArgumentException("caseInstanceId must not be null"); }
jobQuery.caseInstanceId(caseInstanceId);

boolean hasCaseInstanceId(String id) { return id != null; }

try {
    jobQuery.caseInstanceId(caseInstanceId);
} catch (FlowableIllegalArgumentException e) {
    logger.warn("caseInstanceId was null", e);
}

When it happens

Trigger: Calling jobQuery.caseInstanceId(null), e.g. when the case instance id comes from a nullable variable, an entity that was not found, or an unset execution/plan-item context.

Common situations: A CaseInstance lookup returned null (wrong id or instance already ended/purged); job query built generically for both process and case jobs with only the process id set; deserialized task/plan-item data missing the caseInstanceId field.

Related errors

• Null planItemInstance passed
• after time is null
• user id is null
• Provided scope id is null
• Provided sub scope id is null

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