flowable/flowable-engine · error · FlowableIllegalArgumentException

messageName cannot be null

Error message

messageName cannot be null

What it means

MessageEventReceivedCmd.execute() validates that a messageName was supplied before delivering a message to a waiting execution; a null messageName throws FlowableIllegalArgumentException. Correlating a message event requires the name that the message start/boundary/intermediate event subscribed with.

Solutions

1. Pass the exact message name declared on the BPMN message event element.
2. If the name comes from external input, null/empty-check before calling the runtime service.
3. Use runtimeService.createExecutionQuery().messageEventSubscriptionName(name) to confirm the name you intend to use.
4. Catch FlowableIllegalArgumentException when the message may legitimately lack a name and log/skip.

Example fix

// before
runtimeService.messageEventReceived(msgName, executionId); // msgName may be null
// after
if (msgName == null || msgName.isEmpty()) {
    throw new IllegalArgumentException("Message name missing from payload");
}
runtimeService.messageEventReceived(msgName, executionId);

if (messageName == null || messageName.isBlank()) {
    throw new IllegalArgumentException("messageName is required to correlate a message event");
}

boolean isValidMessageName(String n) { return n != null && !n.isBlank(); }

try {
    runtimeService.messageEventReceived(messageName, executionId, payload);
} catch (FlowableIllegalArgumentException e) {
    log.warn("Cannot deliver message: {}", e.getMessage());
}

When it happens

Trigger: Calling runtimeService.messageEventReceived(null, executionId) or messageEventReceived(null, executionId, payload), or building MessageEventReceivedCmd with a null messageName.

Common situations: The message name comes from an incoming webhook/queue message field that is null; variable holding the name not set; mixing up messageName with executionId argument order.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Business key is null
• Business status is null
• bytes is null
• caseInstanceId is null
• caseInstanceId is null

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/MessageEventReceivedCmd.java:68

            this.payload = new HashMap<>(processVariables);

        } 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 FlowableIllegalArgumentException("messageName cannot be null");
        }

        if (Flowable5Util.isFlowable5ProcessDefinitionId(commandContext, execution.getProcessDefinitionId())) {
            Flowable5CompatibilityHandler compatibilityHandler = Flowable5Util.getFlowable5CompatibilityHandler();
            compatibilityHandler.messageEventReceived(messageName, executionId, payload, async);
            return null;
        }

        ProcessEngineConfigurationImpl processEngineConfiguration = CommandContextUtil.getProcessEngineConfiguration(commandContext);
        EventSubscriptionService eventSubscriptionService = processEngineConfiguration.getEventSubscriptionServiceConfiguration().getEventSubscriptionService();
        List<EventSubscriptionEntity> eventSubscriptions = eventSubscriptionService.findEventSubscriptionsByNameAndExecution(MessageEventHandler.EVENT_HANDLER_TYPE, messageName, executionId);

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

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

View on GitHub (pinned to d6d39ce1c6)