{"record":{"id":"5f835dbadabb4fc7","repo":"quarkusio/quarkus","slug":"unsupported-address-type","errorCode":null,"errorMessage":"unsupported address type: ","messagePattern":"unsupported address type: ","errorType":"exception","errorClass":"ChannelException","httpStatus":null,"severity":"error","filePath":"extensions/netty/runtime/src/main/java/io/quarkus/netty/runtime/virtual/VirtualChannelRegistry.java","lineNumber":36,"sourceCode":"import java.net.SocketAddress;\nimport java.util.concurrent.ConcurrentMap;\n\nimport io.netty.channel.Channel;\nimport io.netty.channel.ChannelException;\nimport io.netty.util.internal.PlatformDependent;\nimport io.netty.util.internal.StringUtil;\n\nfinal class VirtualChannelRegistry {\n\n    private static final ConcurrentMap<VirtualAddress, Channel> boundChannels = PlatformDependent.newConcurrentHashMap();\n\n    static VirtualAddress register(\n            Channel channel, VirtualAddress oldLocalAddress, SocketAddress localAddress) {\n        if (oldLocalAddress != null) {\n            throw new ChannelException(\"already bound\");\n        }\n        if (!(localAddress instanceof VirtualAddress)) {\n            throw new ChannelException(\"unsupported address type: \" + StringUtil.simpleClassName(localAddress));\n        }\n\n        VirtualAddress addr = (VirtualAddress) localAddress;\n        if (VirtualAddress.ANY.equals(addr)) {\n            addr = new VirtualAddress(channel);\n        }\n\n        Channel boundChannel = boundChannels.putIfAbsent(addr, channel);\n        if (boundChannel != null) {\n            throw new ChannelException(\"address already in use by: \" + boundChannel);\n        }\n        return addr;\n    }\n\n    static Channel get(SocketAddress localAddress) {\n        return boundChannels.get(localAddress);\n    }\n","sourceCodeStart":18,"sourceCodeEnd":54,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/netty/runtime/src/main/java/io/quarkus/netty/runtime/virtual/VirtualChannelRegistry.java#L18-L54","documentation":"VirtualChannelRegistry.register only accepts local addresses that are instances of VirtualAddress. Passing any other SocketAddress implementation (e.g. InetSocketAddress, DomainSocketAddress) to the virtual transport's bind path throws ChannelException naming the offending class.","triggerScenarios":"Binding a virtual-transport channel with a plain SocketAddress that is not a VirtualAddress; mixing regular Netty bootstraps with the virtual channel registry; passing a remote or resolved address object from another transport.","commonSituations":"Code shared between real-socket and virtual (in-memory) transports where the address type differs per environment; tests that build InetSocketAddress but run against the virtual transport; wrong channel type instantiation (VirtualChannel vs NioServerSocketChannel).","solutions":["Construct and pass a VirtualAddress (e.g. new VirtualAddress(channel) or VirtualAddress.ANY) instead of InetSocketAddress.","Ensure the bootstrap is configured for the virtual transport channel types when using virtual addresses.","Refactor address creation behind an abstraction so the correct address type is produced per transport."],"exampleFix":"// before\nchannel.bind(new InetSocketAddress(\"localhost\", 8080)); // virtual transport: fails\n// after\nchannel.bind(VirtualAddress.ANY); // or new VirtualAddress(channel)","handlingStrategy":"validation","validationCode":"if (!(socketAddress instanceof VirtualAddress)) {\n    throw new IllegalArgumentException(\"virtual transport requires VirtualAddress, got \"\n        + socketAddress.getClass().getName());\n}","typeGuard":"static boolean isVirtualAddress(SocketAddress addr) {\n    return addr instanceof VirtualAddress;\n}","tryCatchPattern":"try {\n    channel.bind(localAddress).sync();\n} catch (ChannelException e) {\n    if (e.getMessage().startsWith(\"unsupported address type\")) {\n        channel.bind(toVirtualAddress(localAddress)).sync();\n    } else { throw e; }\n}","preventionTips":["Only pass VirtualAddress instances to the virtual transport bind","Keep address construction next to transport selection","Add unit tests asserting the address type used per transport"],"tags":["netty","virtual-channel","address-type","bind"],"backgroundTag":"unsupported-address-type","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}