flowable/flowable-engine · error · FlowableIllegalArgumentException

Entity cannot be null.

Error message

Entity cannot be null.

What it means

FlowableEntityExceptionEventImpl wraps an entity event carrying a Throwable cause (e.g. entity FAILED events). Its constructor validates the entity and throws FlowableIllegalArgumentException if the entity is null; only the cause may be null.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/delegate/event/impl/FlowableEntityExceptionEventImpl.java:34

import org.flowable.common.engine.api.delegate.event.FlowableEngineEntityEvent;
import org.flowable.common.engine.api.delegate.event.FlowableEngineEventType;
import org.flowable.common.engine.api.delegate.event.FlowableEvent;
import org.flowable.common.engine.api.delegate.event.FlowableExceptionEvent;

/**
 * Base class for all {@link FlowableEvent} implementations, represents an exception occurred, related to an entity.
 *
 * @author Frederik Heremans
 */
public class FlowableEntityExceptionEventImpl extends FlowableProcessEventImpl implements FlowableEngineEntityEvent, FlowableExceptionEvent {

    protected Object entity;
    protected Throwable cause;

    public FlowableEntityExceptionEventImpl(Object entity, FlowableEngineEventType type, Throwable cause) {
        super(type);
        if (entity == null) {
            throw new FlowableIllegalArgumentException("Entity cannot be null.");
        }
        this.entity = entity;
        this.cause = cause;
    }

    @Override
    public Object getEntity() {
        return entity;
    }

    @Override
    public Throwable getCause() {
        return cause;
    }
}

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Resolve the actual entity before constructing the exception event
2. If the entity is unavailable, use a different event type that does not require an entity
3. Add an upstream null guard before dispatching the event

Example fix

// before
new FlowableEntityExceptionEventImpl(entity, FlowableEngineEventType.ENTITY_DELETED, cause);
// after
Objects.requireNonNull(entity, "entity required for exception event");
new FlowableEntityExceptionEventImpl(entity, FlowableEngineEventType.ENTITY_DELETED, cause);

if (entity == null) { throw new IllegalArgumentException("entity required before dispatching entity exception event"); }

boolean canDispatch = entity != null;

try { new FlowableEntityExceptionEventImpl(entity, type, cause); } catch (FlowableIllegalArgumentException e) { log.warn("skipped failure event: no entity"); }

When it happens

Trigger: Constructing new FlowableEntityEventExceptionImpl(null, type, cause) — usually in custom event creation for failed-entity events with a null entity reference.

Common situations: Custom event-listener bridges that build failure events after a failed entity lookup; engine integrations emitting error events with lost entity references.

Related errors

• Entity cannot be null.
• categoryLike is null
• categoryNotEquals is null
• name is null
• nameLike is null

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