flowable/flowable-engine · error · FlowableIllegalArgumentException

Provided scope id is null

Error message

Provided scope id is null

What it means

DeadLetterJobQueryImpl.scopeId() throws FlowableIllegalArgumentException when the scopeId parameter is null. scopeId identifies the owning scope (process, case, etc.) of the jobs. Note that convenience wrappers such as caseInstanceId() delegate to scopeId (often together with scopeType), so a null case instance id can surface as this scopeId error.

Solutions

1. Null-check the id (or the wrapped caseInstanceId) before calling scopeId(...)
2. Omit the scope filter to query dead-letter jobs across all scopes
3. When using caseInstanceId(...), remember it also sets scopeType - pass a non-null id or skip both
4. Trace why the scope id is missing (entity not persisted, wrong variable name, failed lookup)

Example fix

// before
query.caseInstanceId(caseInstanceId); // throws here when null

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

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

boolean hasScopeId(EntityWithScope e) { return e != null && e.getScopeId() != null; }

try {
    return query.caseInstanceId(caseInstanceId).list();
} catch (FlowableIllegalArgumentException e) {
    throw new InvalidQueryRequestException("scope/case instance id must not be null", e);
}

When it happens

Trigger: Calling deadLetterJobQuery().scopeId(null), or caseInstanceId(null) which delegates to scopeId and triggers this check; passing a scope id read from an entity or message whose field was not populated.

Common situations: CMMN/case integrations querying jobs for a case instance whose id variable is null because the case was never started or the lookup failed; generic scope-handling code that passes through whatever id it received without a null guard.

Related errors

• callbackId is null
• Candidate group is null
• Candidate group list is null
• Candidate user is null
• Deployment id is null

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

Appendix: source

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

    }
    
    @Override
    public DeadLetterJobQueryImpl elementName(String elementName) {
        if (elementName == null) {
            throw new FlowableIllegalArgumentException("Provided element name is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.elementName = elementName;
        } else {
            this.elementName = elementName;
        }
        return this;
    }
    
    @Override
    public DeadLetterJobQueryImpl scopeId(String scopeId) {
        if (scopeId == null) {
            throw new FlowableIllegalArgumentException("Provided scope id is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.scopeId = scopeId;
        } else {
            this.scopeId = scopeId;
        }
        return this;
    }

    @Override
    public DeadLetterJobQuery scopeIds(Collection<String> scopeIds) {
        if (scopeIds == null) {
            throw new FlowableIllegalArgumentException("Provided scope ids are null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.scopeIds = scopeIds;
        } else {
            this.scopeIds = scopeIds;

View on GitHub (pinned to d6d39ce1c6)