flowable/flowable-engine · error · IllegalArgumentException

Queues in <channelDefinition> must not be null

Error message

Queues in <channelDefinition> must not be null

What it means

resolveQueues requires the RabbitInboundChannelModel to carry a non-null queues collection before building the listener endpoint. A null queues value means the channel definition has no target queues at all, so an IllegalArgumentException is thrown.

Source

Thrown at modules/flowable-event-registry-spring/src/main/java/org/flowable/eventregistry/spring/rabbit/RabbitChannelDefinitionProcessor.java:175

    protected String resolveExpressionAsStringOrInteger(String value, String attribute) {
        if (!StringUtils.hasLength(value)) {
            return null;
        }
        Object resolved = resolveExpression(value);
        if (resolved instanceof String) {
            return (String) resolved;
        } else if (resolved instanceof Integer) {
            return resolved.toString();
        } else {
            throw new IllegalStateException("The [" + attribute + "] must resolve to a String. "
                + "Resolved to [" + resolved.getClass() + "] for [" + value + "]");
        }
    }

    protected String[] resolveQueues(RabbitInboundChannelModel channelDefinition) {
        Collection<String> queues = channelDefinition.getQueues();
        if (queues == null) {
            throw new IllegalArgumentException("Queues in " + channelDefinition + " must not be null");
        }

        List<String> resultQueues = new ArrayList<>();

        for (String queue : queues) {
            resolveQueues(resolveExpression(queue), resultQueues, channelDefinition);
        }

        return resultQueues.toArray(new String[0]);
    }

    protected void resolveQueues(Object resolvedValue, List<String> result, RabbitInboundChannelModel channelDefinition) {
        Object resolvedValueToUse = resolvedValue;
        if (resolvedValueToUse instanceof String[]) {
            resolvedValueToUse = Arrays.asList((String[]) resolvedValueToUse);
        }

        if (resolvedValueToUse instanceof String) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Set at least one queue in the channel definition's queues collection
2. Check the definition source (JSON/XML/builder) to ensure the 'queues' key is present and not dropped by deserialization
3. If queues are meant to be provided via exchange/routingKey instead, verify you are using the correct channel definition variant
4. Validate the channel model before passing it to the processor

Example fix

// before
RabbitInboundChannelModel def = new RabbitInboundChannelModel();
// queues never set -> getQueues() == null
// after
RabbitInboundChannelModel def = new RabbitInboundChannelModel();
def.setQueues(Collections.singletonList("my-queue"));

if (channelDefinition.getQueues() == null || channelDefinition.getQueues().isEmpty()) {
    throw new IllegalArgumentException("Rabbit inbound channel definition must declare at least one queue: " + channelDefinition);
}

try {
    processor.process(channelDefinition);
} catch (IllegalArgumentException ex) {
    log.error("Channel definition incomplete: {}", ex.getMessage());
    throw ex;
}

When it happens

Trigger: Processing an inbound Rabbit channel definition whose getQueues() returns null — typically the definition was created without the queues property populated, before createRabbitListenerEndpoint runs.

Common situations: Hand-written or generated channel definition JSON/XML missing the queues field; deserialization silently producing null when the key is absent; a code path that conditionally sets queues but never does.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• The [<attribute>] must resolve to a String. Resolved to [<cl
• Channel definition <channelDefinition> cannot resolve <resol
• Invalid priority value for <channelDefinition> (must be an i
• Could not register rabbit listener endpoint on [<channelDefi
• ackMode in definition [ <channelDefinition> ] must resolve t

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