flowable/flowable-engine · error · FlowableIllegalArgumentException

Provided sub scope id is null

Error message

Provided sub scope id is null

What it means

DeadLetterJobQueryImpl.subScopeId() throws FlowableIllegalArgumentException when the subScopeId parameter is null. subScopeId targets a nested scope such as a plan item instance (the planItemInstanceId() wrapper delegates here, typically alongside scopeType), and null is rejected at query construction time.

Solutions

1. Null-check the subScopeId (or planItemInstanceId) before calling
2. Omit the sub-scope filter to search jobs of the whole parent scope
3. Remember planItemInstanceId(...) also sets scopeType - treat id and type as a pair and guard both
4. Investigate why the plan item instance id is missing (wrong stage, case already terminated)

Example fix

// before
query.planItemInstanceId(planItemId); // throws when planItemId is null

// after
DeadLetterJobQuery query = jobService.createDeadLetterJobQuery();
if (planItemId != null) {
    query = query.planItemInstanceId(planItemId);
}

if (planItemInstanceId != null) {
    query = query.planItemInstanceId(planItemInstanceId);
}

boolean hasSubScopeId(String subScopeId) { return subScopeId != null && !subScopeId.trim().isEmpty(); }

try {
    return query.subScopeId(subScopeId).list();
} catch (FlowableIllegalArgumentException e) {
    throw new InvalidQueryRequestException("subScopeId/planItemInstanceId must not be null", e);
}

When it happens

Trigger: Calling deadLetterJobQuery().subScopeId(null), or planItemInstanceId(null) which delegates to subScopeId; passing a plan item instance id obtained from a failed lookup or an unset entity field.

Common situations: CMMN case work where the plan item instance was completed/removed and its lookup now returns null; generic helper methods that forward optional sub-scope ids without guards; test fixtures missing the id.

Related errors

• callbackId is null
• Parent id is null
• state is null
• user id is null
• activatedBefore is null

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

Appendix: source

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

            this.scopeIds = scopeIds;
        }
        return this;
    }
    
    @Override
    public DeadLetterJobQueryImpl withoutScopeId() {
        if (inOrStatement) {
            this.currentOrQueryObject.withoutScopeId = true;
        } else {
            this.withoutScopeId = true;
        }
        return this;
    }
    
    @Override
    public DeadLetterJobQueryImpl subScopeId(String subScopeId) {
        if (subScopeId == null) {
            throw new FlowableIllegalArgumentException("Provided sub scope id is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.subScopeId = subScopeId;
        } else {
            this.subScopeId = subScopeId;
        }
        return this;
    }
    
    @Override
    public DeadLetterJobQueryImpl scopeType(String scopeType) {
        if (scopeType == null) {
            throw new FlowableIllegalArgumentException("Provided scope type is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.scopeType = scopeType;
        } else {
            this.scopeType = scopeType;

View on GitHub (pinned to d6d39ce1c6)