Fixing Dynamic Router Issue in Spring Integration with Spring Boot 3.x Upgrade

Fixing Dynamic Router Issue in Spring Integration with Spring Boot 3.x Upgrade
Photo by Dima Solomin / Unsplash


Spring Integration provides powerful tools for routing messages dynamically based on various criteria. However, upgrading to Spring Boot 3.x may introduce unexpected issues, particularly with dynamic routers configured using XML and annotated methods. In this post, we'll explore a common issue encountered after upgrading and discuss how to resolve it effectively.


In a Spring Integration application, dynamic routers play a crucial role in directing messages based on runtime conditions. These routers can be configured using XML or annotated methods, where you specify input channels, header names, and routing logic.

The Problem:

After upgrading to Spring Boot 3.x, dynamic routers with default output channels in XML configuration or annotated methods may stop working as expected. This issue arises because setting a default output channel also resets the channelKeyFallback option to false, starting from Spring Integration version 6.0. Unfortunately, there is no direct way to set channelKeyFallback to true explicitly in XML configuration.

partial code from, the spring integration router implementation revealed why the router not worked after the upgrade.

	public void setDefaultOutputChannel(MessageChannel defaultOutputChannel) {
		if (!this.channelKeyFallbackSetExplicitly) {
			this.channelKeyFallback = false;
		this.defaultOutputChannelSet = true;

	private void addChannelFromString(Collection<MessageChannel> channels, String channelKey, Message<?> message) {
		if (channelKey.indexOf(',') != -1) {
			for (String name : StringUtils.tokenizeToStringArray(channelKey, ",")) {
				addChannelFromString(channels, name, message);

		// if the channelMappings contains a mapping, we'll use the mapped value
		// otherwise, the String-based channelKey itself will be used as the channel name
		String channelName = this.channelKeyFallback ? channelKey : null;
		boolean mapped = false;
		if (this.channelMappings.containsKey(channelKey)) {
			channelName = this.channelMappings.get(channelKey);
			mapped = true;
		if (channelName != null) {
			addChannel(channels, message, channelName, mapped);


There are two main options to address this issue in XML configuration:

Option A: Not Set Default Output Channel

By not setting the default output channel, the channelKeyFallback option remains unchanged, allowing the router to fallback to using channel names as keys.

Option B: Set Up Channel Mapping Explicitly

Define explicit channel mappings for all possible values of the header, ensuring that there are no unmatched cases.

Example Implementation:

<int:header-value-router input-channel="inputChannel" header-name="testHeader">
    <int:mapping value="foo" channel="fooChannel" />
    <int:mapping value="bar" channel="barChannel" />

Annotated Method:

public String failedServiceRoute(Message<Long> recordsFound) {
    // ... return dynamic channel based on message header


After upgrading to Spring Boot 3.x, it's essential to ensure that dynamic routers in your Spring Integration application continue to function properly. By understanding the changes in behaviour and following the recommended solutions provided in the Spring Integration documentation, you can resolve any issues efficiently. Whether opting not to set a default output channel or setting up explicit channel mappings, these strategies ensure proper message routing and maintain application functionality.

For more details, refer to the Spring Integration documentation and Dynamic Routers guide.

Subscribe to Post, Code and Quiet Time.

Don’t miss out on the latest issues. Sign up now to get access to the library of members-only issues.