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

Pass the failing entity (typically the Job/Execution) into the builder.

flowable/flowable-engine · error · ActivitiIllegalArgumentException

Entity cannot be null.

Error message

Entity cannot be null.

What it means

ActivitiEntityExceptionEventImpl is the entity event variant that also carries a Throwable cause (e.g. ENTITY_JOB_FAILED). Its constructor validates the entity is non-null, throwing ActivitiIllegalArgumentException otherwise — an exception event without its subject entity is meaningless.

Source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/delegate/event/impl/ActivitiEntityExceptionEventImpl.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 ActivitiEntityExceptionEventImpl extends ActivitiEventImpl implements FlowableEngineEntityEvent, FlowableExceptionEvent {

    protected Object entity;
    protected Throwable cause;

    public ActivitiEntityExceptionEventImpl(Object entity, FlowableEngineEventType type, Throwable cause) {
        super(type);
        if (entity == null) {
            throw new ActivitiIllegalArgumentException("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

Pass the failing entity (typically the Job/Execution) into the builder.
Guard with a null check before constructing/dispatching.
If only the cause is available without an entity, use a plain ActivitiExceptionEvent instead of the entity variant.

Example fix

// before
dispatch(new ActivitiEntityExceptionEventImpl(null, ENTITY_JOB_FAILED, t));
// after
if (job != null) {
    dispatch(new ActivitiEntityExceptionEventImpl(job, ENTITY_JOB_FAILED, t));
}

Defensive patterns

Strategy: type-guard

Validate before calling

if (entity == null || cause == null) { return; }

Type guard

boolean canDispatchExceptionEvent(Object entity, Throwable cause) { return entity != null; }

Try / catch

try { dispatchFailureEvent(entity, cause); } catch (ActivitiIllegalArgumentException e) { logger.warn("Cannot dispatch exception event: no entity", e); }

Prevention

Only construct entity exception events inside hooks that already hold the entity
Use ActivitiEventBuilder.createEntityExceptionEvent with the actual Job/Execution
Log-and-skip when the entity has been removed concurrently

When it happens

Trigger: new ActivitiEntityExceptionEventImpl(null, FlowableEngineEventType.ENTITY_JOB_FAILED, cause) or ActivitiEventBuilder.createEntityExceptionEvent(type, null, cause).

Common situations: Custom failure-reporting code building job/execution exception events where the entity lookup failed; hand-constructed events in tests or instrumentation around async job failure handling.

Related errors

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