flowable/flowable-engine · error · ActivitiIllegalArgumentException

messageName cannot be null

Error message

messageName cannot be null

What it means

Thrown by MessageEventReceivedCmd.execute() when messageName is null. To deliver a message to a waiting execution, the engine must look up message event subscriptions by name, so a null name is rejected with ActivitiIllegalArgumentException.

Solutions

1. Pass the message name that the receiving catch message event was declared with
2. Validate the name before calling (non-null, matches BPMN messageRef)
3. Log the intended message name at the call site to catch null-producing lookups

Example fix

// before
runtimeService.messageEventReceived(messageName, executionId);
// after
if (messageName == null) throw new IllegalArgumentException("messageName required");
runtimeService.messageEventReceived(messageName, executionId);

if (messageName == null || messageName.isEmpty()) throw new IllegalArgumentException("messageName required");

boolean canDeliver(String messageName, String executionId) { return messageName != null && executionId != null; }

try { runtimeService.messageEventReceived(messageName, executionId, payload); } catch (ActivitiIllegalArgumentException e) { log.error("bad message correlation args"); throw e; }

When it happens

Trigger: runtimeService.messageEventReceived(null, executionId) or messageEventReceived(null, executionId, payload); also trigger with async=true when constructing MessageEventReceivedCmd with null messageName.

Common situations: Message name read from a process variable or header that was not set; refactored caller dropped the name argument; configuration for the correlating message missing.

Related errors

• executionId is null
• id is null
• key is null
• keyLike is null
• nameLike is null

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

Appendix: source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cmd/MessageEventReceivedCmd.java:67

            }

        } else {
            this.payload = null;
        }
        this.async = false;
    }

    public MessageEventReceivedCmd(String messageName, String executionId, boolean async) {
        super(executionId);
        this.messageName = messageName;
        this.payload = null;
        this.async = async;
    }

    @Override
    protected Void execute(CommandContext commandContext, ExecutionEntity execution) {
        if (messageName == null) {
            throw new ActivitiIllegalArgumentException("messageName cannot be null");
        }

        List<EventSubscriptionEntity> eventSubscriptions = commandContext.getEventSubscriptionEntityManager()
                .findEventSubscriptionsByNameAndExecution(MessageEventHandler.EVENT_HANDLER_TYPE, messageName, executionId);

        if (eventSubscriptions.isEmpty()) {
            throw new ActivitiException("Execution with id '" + executionId + "' does not have a subscription to a message event with name '" + messageName + "'");
        }

        // there can be only one:
        EventSubscriptionEntity eventSubscriptionEntity = eventSubscriptions.get(0);

        eventSubscriptionEntity.eventReceived(payload, async);

        return null;
    }

}

View on GitHub (pinned to d6d39ce1c6)