What causes "Provided event subscription id is null" in flowable/flowable-engine?

Check the id for null before calling eventSubscriptionId and skip the criterion (or the whole query) when absent

flowable/flowable-engine · error · ActivitiIllegalArgumentException

Provided event subscription id is null

Error message

Provided event subscription id is null

What it means

This Activiti (Flowable 5) error is thrown by EventSubscriptionQueryImpl.eventSubscriptionId when the id passed in is null. Query criterion setters validate arguments eagerly so a malformed query fails fast at build time rather than producing an opaque failure or wrong results when the query is executed via the CommandExecutor. It signals a programming mistake by the caller, not a runtime state problem.

Solutions

Check the id for null before calling eventSubscriptionId and skip the criterion (or the whole query) when absent
Fix the upstream lookup so a real event subscription id is produced before building the query
If null means 'no filter', do not call the setter at all instead of passing null
Wrap the query construction in a guard that asserts required filter values are non-null

Example fix

// before
EventSubscriptionQuery q = runtimeService.createEventSubscriptionQuery().eventSubscriptionId(subId);
// after
if (subId != null) {
    EventSubscriptionQuery q = runtimeService.createEventSubscriptionQuery().eventSubscriptionId(subId);
} else {
    EventSubscriptionQuery q = runtimeService.createEventSubscriptionQuery();
}

Defensive patterns

Strategy: validation

Validate before calling

if (eventSubscriptionId == null) { throw new IllegalArgumentException("eventSubscriptionId must be non-null before querying"); }
EventSubscriptionQuery q = runtimeService.createEventSubscriptionQuery().eventSubscriptionId(eventSubscriptionId);

Type guard

boolean hasId(String id) { return id != null && !id.trim().isEmpty(); }

Try / catch

try {
    query.eventSubscriptionId(id);
} catch (org.activiti.engine.ActivitiIllegalArgumentException e) {
    // id was null: fix caller logic or skip the criterion
}

Prevention

Null-check ids obtained from entity lookups before using them as query criteria
Omit optional setters instead of passing null
Use Objects.requireNonNull with a clear message at the id's origin
Avoid relying on APIs that may return null ids; prefer Optional lookups

When it happens

Trigger: Calling runtimeService.createEventSubscriptionQuery().eventSubscriptionId(null) or passing a variable/field that is null because an earlier lookup (e.g. eventSubscription.getId()) returned null.

Common situations: Chaining query builders where the id comes from an optional entity; copy-pasted query code where the wrong variable is passed; code refactors where the id lookup was removed or made optional; using a null return from getEventSubscriptions/lookup APIs as query input without checking.

Related errors

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

Appendix: source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/EventSubscriptionQueryImpl.java:49

    protected String eventSubscriptionId;
    protected String eventName;
    protected String eventType;
    protected String executionId;
    protected String processInstanceId;
    protected String activityId;
    protected String tenantId;

    public EventSubscriptionQueryImpl(CommandContext commandContext) {
        super(commandContext);
    }

    public EventSubscriptionQueryImpl(CommandExecutor commandExecutor) {
        super(commandExecutor);
    }

    public EventSubscriptionQueryImpl eventSubscriptionId(String id) {
        if (eventSubscriptionId == null) {
            throw new ActivitiIllegalArgumentException("Provided event subscription id is null");
        }
        this.eventSubscriptionId = id;
        return this;
    }

    public EventSubscriptionQueryImpl eventName(String eventName) {
        if (eventName == null) {
            throw new ActivitiIllegalArgumentException("Provided event name is null");
        }
        this.eventName = eventName;
        return this;
    }

    public EventSubscriptionQueryImpl executionId(String executionId) {
        if (executionId == null) {
            throw new ActivitiIllegalArgumentException("Provided execution id is null");
        }
        this.executionId = executionId;

View on GitHub (pinned to d6d39ce1c6)