flowable/flowable-engine · error · FlowableIllegalArgumentException

The listener to be registered must not be null.

Error message

The listener to be registered must not be null.

What it means

AddEventListenerCommand validates that the FlowableEventListener passed to CmmnRuntimeService.addEventListener is non-null before registering it with the engine's event dispatcher. A null listener cannot receive events, so a FlowableIllegalArgumentException is thrown inside the command.

Solutions

1. Ensure a non-null FlowableEventListener instance is constructed or injected before calling addEventListener
2. Check DI wiring (Spring bean exists, @Autowired/@Inject satisfied, bean name correct)
3. Guard the call site: if (listener != null) before registering
4. Log at startup which listeners were registered to catch silent null wiring early

Example fix

// before
cmmnRuntimeService.addEventListener(myListener, arraysOfTypes);
// after
Objects.requireNonNull(myListener, "event listener must be configured");
cmmnRuntimeService.addEventListener(myListener, arrayOfTypes);

if (listener == null) throw new IllegalArgumentException("listener must be configured before registration");
cmmnRuntimeService.addEventListener(listener, types);

boolean canRegister(FlowableEventListener l) { return l != null; }

try {
    cmmnRuntimeService.addEventListener(listener);
} catch (FlowableIllegalArgumentException e) {
    log.error("Listener registration failed: configure the listener bean", e);
}

When it happens

Trigger: Calling cmmnRuntimeService.addEventListener(null) or cmmnRuntimeService.addEventListener(null, types...) — typically when the listener variable was never initialized, was returned null by a factory/spring lookup, or was accidentally cleared in configuration.

Common situations: Spring bean injection failure leaving the listener field null, conditional wiring that skipped listener creation, refactoring that renamed the listener bean, or passing the result of map.get("listener") which is null.

Related errors

• after time is null
• Business key is null
• Business status is null
• bytes array is null
• callbackIds is null or empty

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

Appendix: source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/cmd/AddEventListenerCommand.java:45

public class AddEventListenerCommand  implements Command<Void> {

    protected FlowableEventListener listener;
    protected FlowableEngineEventType[] types;

    public AddEventListenerCommand(FlowableEventListener listener, FlowableEngineEventType[] types) {
        this.listener = listener;
        this.types = types;
    }

    public AddEventListenerCommand(FlowableEventListener listener) {
        super();
        this.listener = listener;
    }

    @Override
    public Void execute(CommandContext commandContext) {
        if (listener == null) {
            throw new FlowableIllegalArgumentException("The listener to be registered must not be null.");
        }

        if (types != null) {
            CommandContextUtil.getCmmnEngineConfiguration(commandContext).getEventDispatcher().addEventListener(listener, types);
        } else {
            CommandContextUtil.getCmmnEngineConfiguration(commandContext).getEventDispatcher().addEventListener(listener);
        }

        return null;
    }
}

View on GitHub (pinned to d6d39ce1c6)