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.

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();
}
Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Try / catch

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

Prevention

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


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

Appendix: 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)