flowable/flowable-engine · error · FlowableIllegalArgumentException

rootScopeId is empty

Error message

rootScopeId is empty

What it means

InternalEntityLinkQueryImpl.rootScopeId sets the root scope filter for entity link queries. The library throws FlowableIllegalArgumentException when the caller passes null or an empty string, because an empty rootScopeId would produce a meaningless query filter. This is a fail-fast argument validation guard on a query builder method.

Solutions

1. Ensure a non-empty rootScopeId is resolved before building the query (check the source entity's root scope id).
2. Guard the caller: only call rootScopeId when the value is non-null and non-empty, or use a different query path that doesn't filter by root scope.
3. Verify the upstream entity data actually has a root scope id populated; fix the data or creation code if it is missing.

Example fix

// before
query.rootScopeId(processInstance.getRootScopeId());
// after
if (StringUtils.isNotEmpty(processInstance.getRootScopeId())) {
    query.rootScopeId(processInstance.getRootScopeId());
}

if (rootScopeId == null || rootScopeId.isEmpty()) {
    throw new IllegalArgumentException("rootScopeId must be provided before querying");
}
internalEntityLinkQuery.rootScopeId(rootScopeId);

boolean hasRootScopeId(String s) { return s != null && !s.trim().isEmpty(); }

try {
    query.rootScopeId(rootScopeId);
} catch (FlowableIllegalArgumentException e) {
    LOG.warn("Rejected empty rootScopeId: {}", e.getMessage());
}

When it happens

Trigger: Calling internalEntityLinkQuery.rootScopeId(null) or rootScopeId("") while building an InternalEntityLinkQuery.

Common situations: Populating the query from a runtime variable, request parameter, or entity field that is null/not yet set (e.g. an entity without an assigned root scope), or refactoring code where the scope id lookup returned empty.

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

• hierarchyType is empty
• linkType is empty
• rootScopeType is empty
• callbackIds is null or empty
• Cannot combine onlyTimers() with onlyMessages() in the same…

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

Appendix: source

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

            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");
        }
        this.rootScopeId = rootScopeId;
        return this;
    }

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

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

View on GitHub (pinned to d6d39ce1c6)