flowable/flowable-engine · error · FlowableIllegalArgumentException

scopeDefinitionId is empty

Error message

scopeDefinitionId is empty

What it means

FlowableIllegalArgumentException thrown by InternalEntityLinkQueryImpl.scopeDefinitionId when the supplied scope definition id is null or empty. The query requires a non-empty definition id to filter entity links by scope definition.

Solutions

1. Validate the definition id is non-blank before building the query.
2. Ensure the definition was deployed and its id retrieved via the repository service.
3. Conditionally apply the filter only when the id exists.

Example fix

// before
query.scopeDefinitionId(defId).list();

// after
if (StringUtils.isNotBlank(defId)) {
    query.scopeDefinitionId(defId).list();
}

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

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

When it happens

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

Common situations: The process/case definition id was not resolved (e.g. deployment lookup failed) before building the query; passing an empty default value from configuration.

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
• referenceScopeId is empty
• referenceScopeType is empty
• scopeId is empty
• scopeIds is empty

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

Appendix: source

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

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

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

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

View on GitHub (pinned to d6d39ce1c6)