flowable/flowable-engine · error · FlowableIllegalArgumentException

Provided case definition id is null

Error message

Provided case definition id is null

What it means

JobQueryImpl.caseDefinitionId(String) rejects a null case definition id with FlowableIllegalArgumentException. After the check it delegates to scopeDefinitionId(caseDefinitionId) and sets scopeType(ScopeTypes.CMMN); the guard exists because querying CMMN jobs by an undefined definition id is meaningless. This is a pure argument-validation error thrown at query-construction time, before any database access.

Solutions

1. Resolve the case definition id via repositoryService.createCaseDefinitionQuery() and verify it is non-null before querying jobs
2. Query by caseDefinitionKey instead if the id is unknown (but still pass a non-null key)
3. Skip the filter when null and query all CMMN jobs, filtering afterwards
4. Check deployment/tenant configuration if the definition should exist

Example fix

// before
CaseDefinition def = repo.createCaseDefinitionQuery().caseDefinitionKey(key).singleResult();
jobQuery.caseDefinitionId(def.getId()); // NPE-prone and can be null
// after
CaseDefinition def = repo.createCaseDefinitionQuery().caseDefinitionKey(key).singleResult();
if (def != null) {
    jobQuery.caseDefinitionId(def.getId());
}

CaseDefinition def = repositoryService.createCaseDefinitionQuery().caseDefinitionId(id).singleResult();
if (def == null) { throw new IllegalArgumentException("Unknown case definition id: " + id); }
jobQuery.caseDefinitionId(id);

boolean isDeployedCaseDefinition(String id) { return id != null && repositoryService.createCaseDefinitionQuery().caseDefinitionId(id).count() > 0; }

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

When it happens

Trigger: Calling jobQuery.caseDefinitionId(null); typically when the definition id came from a CaseDefinitionQuery that returned no results, or from an unset field on a case instance/plan item object.

Common situations: Case definition not deployed under the expected key/tenant so lookups return null; migration/version-upgrade code where the definition id resolution changed; generic job-listing code that shares one builder for process and case definitions.

Related errors

• after time is null
• Null planItemInstance passed
• Provided case definition id is null
• Provided case definition key is null
• Provided case instance id is null

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

Appendix: source

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

            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) {
        if (caseDefinitionKey == null) {
            throw new FlowableIllegalArgumentException("Provided case definition id is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.caseDefinitionKey = caseDefinitionKey;
        } else {
            this.caseDefinitionKey = caseDefinitionKey;
        }
        return this;
    }

View on GitHub (pinned to d6d39ce1c6)