What causes "Entity cannot be null." in flowable/flowable-engine?

Pass the actual engine entity (Task, ExecutionEntity, ProcessInstance, Job, ...) to the constructor/builder.

flowable/flowable-engine · error · ActivitiIllegalArgumentException

Entity cannot be null.

Error message

Entity cannot be null.

What it means

ActivitiEntityEventImpl wraps an engine entity (task, execution, process instance, etc.) in an entity-related event. Its constructor validates the entity is non-null and throws ActivitiIllegalArgumentException otherwise, since an ENTITY_* event with no entity carries no information. It is normally thrown by ActivitiEventBuilder, not user code.

Source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/delegate/event/impl/ActivitiEntityEventImpl.java:32

import org.activiti.engine.ActivitiIllegalArgumentException;
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;

/**
 * Base class for all {@link FlowableEvent} implementations, related to entities.
 * 
 * @author Frederik Heremans
 */
public class ActivitiEntityEventImpl extends ActivitiEventImpl implements FlowableEngineEntityEvent {

    protected Object entity;

    public ActivitiEntityEventImpl(Object entity, FlowableEngineEventType type) {
        super(type);
        if (entity == null) {
            throw new ActivitiIllegalArgumentException("Entity cannot be null.");
        }
        this.entity = entity;
    }

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

View on GitHub (pinned to d6d39ce1c6)

Solutions

Pass the actual engine entity (Task, ExecutionEntity, ProcessInstance, Job, ...) to the constructor/builder.
In custom dispatch code, check entity != null before calling ActivitiEventBuilder.createEntityEvent.
If the entity is null because the row is gone, skip emitting the event instead of constructing one.

Example fix

// before
eventDispatcher.dispatchEvent(ActivitiEventBuilder.createEntityEvent(type, null));
// after
if (entity != null) {
    eventDispatcher.dispatchEvent(ActivitiEventBuilder.createEntityEvent(type, entity));
}

Defensive patterns

Strategy: type-guard

Validate before calling

if (entity == null) { return; // skip event dispatch }

Type guard

boolean canDispatchEntityEvent(Object entity) { return entity != null; }

Try / catch

try { dispatcher.dispatchEvent(builder.build()); } catch (ActivitiIllegalArgumentException e) { logger.warn("Skipped entity event with null entity"); }

Prevention

Always build events through ActivitiEventBuilder factory methods
Re-fetch or verify entity existence before emitting lifecycle events
Guard custom dispatch code with null checks

When it happens

Trigger: new ActivitiEntityEventImpl(null, FlowableEngineEventType.ENTITY_CREATED) or ActivitiEventBuilder.createEntityEvent(type, null) with a null entity.

Common situations: Custom event listeners/builders dispatching events from hooks where the looked-up entity was null (e.g. entity deleted before event build); test code constructing events manually.

Related errors

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