flowable/flowable-engine · error · FlowableIllegalArgumentException

Provided case definition id is null

Error message

Provided case definition id is null

What it means

This FlowableIllegalArgumentException is thrown by SuspendedJobQueryImpl.caseDefinitionId() when the caller passes a null case definition id. The method delegates to scopeDefinitionId() and sets scope type to CMMN; the id null-check fires first. Flowable rejects null here so the query is never built with an invalid definition filter.

Source

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

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

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Resolve the definition via repositoryService.createCaseDefinitionQuery() and null-check before querying jobs
2. Only call caseDefinitionId() with a verified non-null id; use caseDefinitionKey() if you only have a key
3. Handle 'definition not found' explicitly instead of passing null
4. Validate configuration/deployment state before query construction

Example fix

// before
CaseDefinition cd = repositoryService.createCaseDefinitionQuery().caseDefinitionKey(key).singleResult();
query.caseDefinitionId(cd.getId()); // cd may be null
// after
CaseDefinition cd = repositoryService.createCaseDefinitionQuery().caseDefinitionKey(key).singleResult();
if (cd != null) {
    query.caseDefinitionId(cd.getId());
}

CaseDefinition cd = repositoryService.createCaseDefinitionQuery().caseDefinitionId(definitionId).singleResult();
if (cd != null) {
    query.caseDefinitionId(definitionId);
}

boolean hasCaseDefinitionId = caseDefinitionId != null && !caseDefinitionId.isBlank();

try {
    query.caseDefinitionId(caseDefinitionId);
} catch (FlowableIllegalArgumentException e) {
    if (e.getMessage().contains("case definition id is null")) {
        // fall back to caseDefinitionKey-based lookup or fail with a clear message
    } else {
        throw e;
    }
}

When it happens

Trigger: Calling suspendedJobQuery().caseDefinitionId(null), commonly when the definition was not resolved from the repository service, a deployment lookup failed, or an optional parameter was null.

Common situations: RepositoryService lookup by key returned no definition and the code proceeded; configuration specifying a definition id that does not exist in the DB; refactor left a nullable variable in place.

Related errors

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