flowable/flowable-engine · error · FlowableIllegalArgumentException

Provided scope definitionid is null

Error message

Provided scope definitionid is null

What it means

DeadLetterJobQueryImpl.scopeDefinitionId() throws FlowableIllegalArgumentException when the scopeDefinitionId parameter is null. Flowable query builders validate required filter arguments eagerly so that an invalid query fails at construction time rather than producing an empty or malformed SQL query at execution time. Passing null here indicates the caller resolved no definition id (e.g. a case/process definition lookup returned null) and forwarded it anyway.

Source

Thrown at modules/flowable-job-service/src/main/java/org/flowable/job/service/impl/DeadLetterJobQueryImpl.java:311

            this.scopeType = scopeType;
        }
        return this;
    }

    @Override
    public DeadLetterJobQueryImpl withoutScopeType() {
        if (inOrStatement) {
            this.currentOrQueryObject.withoutScopeType = true;
        } else {
            this.withoutScopeType = true;
        }
        return this;
    }

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

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Null-check the definition id before calling scopeDefinitionId and skip the filter (or fail fast with your own message) when it is absent.
2. Verify the upstream lookup (repositoryService/case service) that produced the id actually succeeded and the entity exists.
3. If the filter is optional, build the query conditionally: if (id != null) query.scopeDefinitionId(id).

Example fix

// before
query.scopeDefinitionId(caseInstance.getCaseDefinitionId());
// after
String defId = caseInstance.getCaseDefinitionId();
if (defId != null) {
    query.scopeDefinitionId(defId);
}

if (scopeDefinitionId == null) { throw new IllegalStateException("scopeDefinitionId must be resolved before querying dead-letter jobs"); }
query.scopeDefinitionId(scopeDefinitionId);

boolean hasDefinitionId(String id) { return id != null && !id.isBlank(); }

try { query.scopeDefinitionId(id); } catch (FlowableIllegalArgumentException e) { log.warn("Invalid scopeDefinitionId: {}", e.getMessage()); }

When it happens

Trigger: Calling deadLetterJobQuery().scopeDefinitionId(null) directly, or calling caseDefinitionId(null) which delegates to scopeDefinitionId, with a null String, including inside an or() block.

Common situations: Resolving a definition id from a runtime CaseInstance/ProcessInstance that returned null; forwarding an optional variable or config value that was never set; refactoring code where a previously-set definition id became optional.

Related errors

• rootScopeIds is null or empty
• parentScopeId is null
• parentScopeIds is null or empty
• Process instance id is null
• Root process instance id is null

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