flowable/flowable-engine · error · FlowableIllegalArgumentException

hierarchyType is empty

Error message

hierarchyType is empty

What it means

InternalEntityLinkQueryImpl.hierarchyType sets the hierarchy type filter for entity link queries (e.g. hierarchy-level filtering). It throws FlowableIllegalArgumentException when passed null or an empty string, as an empty hierarchyType cannot define a valid filter. Fail-fast argument validation on the query builder.

Solutions

1. Supply the correct hierarchy type value (e.g. 'root', 'all' depending on the API contract) before querying.
2. Trace the value's origin and fix the code/config that leaves it empty.
3. Omit the hierarchyType filter if not required rather than passing an empty string.

Example fix

// before
query.hierarchyType(hierarchyType); // may be empty
// after
if (StringUtils.isNotEmpty(hierarchyType)) {
    query.hierarchyType(hierarchyType);
}

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

boolean hasHierarchyType(String t) { return t != null && !t.trim().isEmpty(); }

try {
    query.hierarchyType(hierarchyType);
} catch (FlowableIllegalArgumentException e) {
    LOG.warn("hierarchyType not set: {}", e.getMessage());
}

When it happens

Trigger: Calling internalEntityLinkQuery.hierarchyType(null) or hierarchyType("") while building the query.

Common situations: Passing an uninitialized configuration value, mapping a missing request/DTO field into the query, or confusing hierarchyType with scopeType and passing an empty default.

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

• linkType is empty
• rootScopeId 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/5516e0c219e16c66. Report an issue: GitHub.

Appendix: source

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

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

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

    @Override
    public List<E> list() {
        return listProvider.apply(this);
    }

    @Override
    public E singleResult() {
        return singleResultProvider.apply(this);
    }

    public Collection<String> getScopeIds() {
        return scopeIds;
    }

View on GitHub (pinned to d6d39ce1c6)