flowable/flowable-engine · error · FlowableIllegalArgumentException

referenceScopeId is empty

Error message

referenceScopeId is empty

What it means

Fluent-setter validation in InternalEntityLinkQueryImpl.referenceScopeId: the referenced scope id filter is null or blank; entity-link queries need a concrete reference scope, so the empty value is refused.

Solutions

1. Verify the referenced entity exists and capture its id before querying.
2. Null/blank-check the id before invoking the query builder.
3. Correct upstream code that should populate the reference scope id.

Example fix

// before
query.referenceScopeId(childInstanceId).list();

// after
if (StringUtils.isNotBlank(childInstanceId)) {
    query.referenceScopeId(childInstanceId).list();
}

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

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

When it happens

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

Common situations: The referenced entity (e.g. a child process/case instance) was not created, so its id is missing; passing a null return value from a previous service call directly into the query.

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

• referenceScopeDefinitionId 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/79dc06f04564260d. Report an issue: GitHub.

Appendix: source

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

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

    @Override
    public InternalEntityLinkQuery<E> scopeType(String scopeType) {
        if (StringUtils.isEmpty(scopeType)) {
            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");

View on GitHub (pinned to d6d39ce1c6)