flowable/flowable-engine · error · FlowableIllegalArgumentException

referenceScopeDefinitionId is empty

Error message

referenceScopeDefinitionId is empty

What it means

Fluent-setter validation in InternalEntityLinkQueryImpl.referenceScopeDefinitionId: the reference scope definition id filter is null or empty and is rejected before query execution.

Solutions

1. Fetch the referenced definition id via RepositoryService before building the query.
2. Blank-check the value before setting it.
3. Only apply the filter when a definition id is actually known.

Example fix

// before
query.referenceScopeDefinitionId("").list();

// after
if (StringUtils.isNotBlank(refDefId)) {
    query.referenceScopeDefinitionId(refDefId).list();
}

if (StringUtils.isBlank(referenceScopeDefinitionId)) { throw new IllegalArgumentException("referenceScopeDefinitionId required"); }

try {
    links = entityLinkQuery.referenceScopeDefinitionId(refDefId).list();
} catch (FlowableIllegalArgumentException e) {
    links = Collections.emptyList();
}

When it happens

Trigger: Calling InternalEntityLinkQuery.referenceScopeDefinitionId("") or referenceScopeDefinitionId(null).

Common situations: Definition id of the referenced process/case not resolved (missing deployment or wrong definition key); copying a query builder template and leaving the field blank.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• referenceScopeId is empty
• referenceScopeType is empty
• scopeDefinitionId is empty
• scopeId is empty
• scopeIds is empty

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

Appendix: source

Thrown at modules/flowable-entitylink-service/src/main/java/org/flowable/entitylink/service/impl/InternalEntityLinkQueryImpl.java:103

            throw new FlowableIllegalArgumentException("scopeType is empty");
        }
        this.scopeType = scopeType;
        return this;
    }

    @Override
    public InternalEntityLinkQuery<E> referenceScopeId(String referenceScopeId) {
        if (StringUtils.isEmpty(referenceScopeId)) {
            throw new FlowableIllegalArgumentException("referenceScopeId is empty");
        }
        this.referenceScopeId = referenceScopeId;
        return this;
    }

    @Override
    public InternalEntityLinkQuery<E> referenceScopeDefinitionId(String referenceScopeDefinitionId) {
        if (StringUtils.isEmpty(referenceScopeDefinitionId)) {
            throw new FlowableIllegalArgumentException("referenceScopeDefinitionId is empty");
        }
        this.referenceScopeDefinitionId = referenceScopeDefinitionId;
        return this;
    }

    @Override
    public InternalEntityLinkQuery<E> referenceScopeType(String referenceScopeType) {
        if (StringUtils.isEmpty(referenceScopeType)) {
            throw new FlowableIllegalArgumentException("referenceScopeType is empty");
        }
        this.referenceScopeType = referenceScopeType;
        return this;
    }

    @Override
    public InternalEntityLinkQuery<E> rootScopeId(String rootScopeId) {
        if (StringUtils.isEmpty(rootScopeId)) {
            throw new FlowableIllegalArgumentException("rootScopeId is empty");

View on GitHub (pinned to d6d39ce1c6)