AWS SDK v2 netty-nio-client incompatible with Netty 4.2.x IoEventLoopGroup (MultiThreadIoEventLoopGroup not recognized)

[samarprakash]

Describe the bug

When upgrading an application stack to Netty 4.2.x and Reactor Netty 1.3.x, the AWS SDK v2 netty-nio-client fails when providing a Netty 4.2-style EventLoopGroup (e.g. MultiThreadIoEventLoopGroup).

The failure occurs because SdkEventLoopGroup create does not recognize MultiThreadIoEventLoopGroup (Netty 4.2 model) and throws:

IllegalArgumentException: Unknown event loop group : class io.netty.channel.MultiThreadIoEventLoopGroup

This suggests that netty-nio-client still expects 4.1-style EpollEventLoopGroup or NioEventLoopGroup.

So few Key Questions

• Does AWS SDK v2 officially support Netty 4.2.x?
• If not:
  - Is there a roadmap to support 4.2?
  - Is there an estimated release version?
• If yes:
  - Which AWS SDK version should be used?
  - What is the correct way to provide a 4.2-style IoEventLoopGroup?
• Is there a recommended compatibility matrix between:
  - AWS SDK v2
  - Netty

Regression Issue

• Select this option if this issue appears to be a regression.

Expected Behavior

If AWS SDK v2 supports Netty 4.2.x:

• SdkEventLoopGroup create should accept IoEventLoopGroup / MultiThreadIoEventLoopGroup
• OR documentation should clearly state that Netty 4.2.x is not supported

Current Behavior

Only 4.1-style groups are supported:

• EpollEventLoopGroup
• KQueueEventLoopGroup
• NioEventLoopGroup

IoEventLoopGroup (4.2 model) is not recognized.

Reproduction Steps

• Create Netty 4.2 EventLoopGroup

@Bean
public EventLoopGroup eventLoopGroup() {
    return new MultiThreadIoEventLoopGroup(
        8,
        NioIoHandler.newFactory()
    );
}

• Provide it to AWS SDK

@Bean
public SdkEventLoopGroup sdkEventLoopGroup(EventLoopGroup eventLoopGroup) {
    return SdkEventLoopGroup.create(
        eventLoopGroup,
        NioSocketChannel::new
    );
}

• Result

IllegalArgumentException:
Unknown event loop group :
class io.netty.channel.MultiThreadIoEventLoopGroup

Possible Solution

• Add support for Netty 4.2 IoEventLoopGroup

  • Detect IoEventLoopGroup / MultiThreadIoEventLoopGroup
  • Allow user-provided ChannelFactory without strict type checking
  • Avoid instanceof checks tied to 4.1-only classes

• Provide explicit documentation

  • Clearly state that Netty 4.2.x is not supported
  • Provide an official compatibility matrix

• Introduce version-aware factory logic

  • If Netty 4.2 detected, use generic ChannelFactory
  • Avoid relying on concrete EventLoopGroup subclass checks

At minimum, clarification on official Netty 4.2 support status would help users avoid runtime incompatibilities during upgrades.

Additional Information/Context

Netty 4.2 introduces the new IoHandler model and deprecates:
EpollEventLoopGroup, KQueueEventLoopGroup, NioEventLoopGroup
Frameworks such as Reactor Netty 1.3.x are beginning to align with 4.2 APIs.

This creates a compatibility gap for applications using: Spring WebFlux / Reactor Netty, AWS SDK v2 async clients, Shared EventLoopGroups for IO optimization

Currently, users must either - Downgrade Netty to 4.1.x Or use deprecated EventLoopGroup implementations

Clarification on official support would help prevent production incompatibilities.

The incompatibility appears to stem from SdkEventLoopGroup performing instance checks against legacy EventLoopGroup types.

AWS Java SDK version used

V2 SDK (group ID software.amazon.awssdk) - 2.42.4

JDK version used

Java 21

Operating System and version

Linux (Epoll available)

[debora-ito]

Hi @samarprakash

aws-sdk-java-v2/pom.xml

Line 121 in f61e386

<netty.version>4.1.130.Final</netty.version>

The latest Java SDK version uses Netty 4.1.130, but we have plans to upgrade to 4.2.x and we're aware of the changes required to support it. Tracking in PR: #6205.

We are currently working to remove some blockers to merge the PR, will post updates here when we have any.