{"record":{"id":"a19f4d7a282ce8ac","repo":"aeron-io/aeron","slug":"option-conflicts-with-existing-subscription-reliable","errorCode":null,"errorMessage":"option conflicts with existing subscription: reliable=${isReliable} existingChannel=${existingChannel} channel=${channel}","messagePattern":"option conflicts with existing subscription: reliable=(.+?) existingChannel=(.+?) channel=(.+?)","errorType":"exception","errorClass":"InvalidChannelException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/DriverConductor.java","lineNumber":1622,"sourceCode":"    }\n\n    private void checkForClashingSubscription(\n        final SubscriptionParams params, final UdpChannel udpChannel, final int streamId)\n    {\n        final ReceiveChannelEndpoint channelEndpoint = findExistingReceiveChannelEndpoint(udpChannel);\n        if (null != channelEndpoint)\n        {\n            validateUdpChannelAgainstReceiveChannelEndpoint(params, udpChannel, channelEndpoint);\n\n            for (final SubscriptionLink subscription : subscriptionLinks)\n            {\n                final boolean matchesTag = !udpChannel.hasTag() || channelEndpoint.matchesTag(udpChannel);\n\n                if (matchesTag && subscription.matches(channelEndpoint, streamId, params))\n                {\n                    if (params.isReliable != subscription.isReliable())\n                    {\n                        throw new InvalidChannelException(\n                            \"option conflicts with existing subscription: reliable=\" + params.isReliable +\n                                \" existingChannel=\" + subscription.channel() + \" channel=\" +\n                                udpChannel.originalUriString());\n                    }\n\n                    if (params.isRejoin != subscription.isRejoin())\n                    {\n                        throw new InvalidChannelException(\n                            \"option conflicts with existing subscription: rejoin=\" + params.isRejoin +\n                                \" existingChannel=\" + subscription.channel() + \" channel=\" +\n                                udpChannel.originalUriString());\n                    }\n\n                    if (params.isResponse != subscription.isResponse())\n                    {\n                        throw new InvalidChannelException(\n                            \"option conflicts with existing subscription: isResponse=\" + params.isResponse +\n                                \" existingChannel=\" + subscription.channel() + \" channel=\" +","sourceCodeStart":1604,"sourceCodeEnd":1640,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/DriverConductor.java#L1604-L1640","documentation":"Within a single Aeron client, all subscriptions sharing a channel endpoint and streamId must agree on the 'reliable' option. The driver throws this InvalidChannelException when a new addSubscription matches an existing subscription on channel/stream/tag but declares a different reliable value.","triggerScenarios":"Calling Aeron.addSubscription with reliable=false (or true) on a URI/streamId where a subscription with the opposite reliable setting already exists and matches the same endpoint, stream, and tag.","commonSituations":"Two parts of an application independently subscribing to the same channel/stream with divergent reliability config; a shared library component adds subscriptions with its own defaults; copying URIs between services with different ?reliable= values.","solutions":["Align the reliable parameter across all addSubscription calls for the same channel/streamId","Remove or close the conflicting existing subscription first","Use a different streamId or session-id range if different reliability semantics are genuinely needed","Centralize channel URI construction so all subscribers share one config source"],"exampleFix":"// before\naeron.addSubscription(\"aeron:udp?endpoint=localhost:40456|reliable=false\", 1001);\n// after (match existing subscription)\naeron.addSubscription(\"aeron:udp?endpoint=localhost:40456|reliable=true\", 1001);","handlingStrategy":"try-catch","validationCode":"boolean reliable = Boolean.parseBoolean(uriParam(channel, \"reliable\", \"true\"));\n// assert reliable matches the value used by all other subscribers of this channel/streamId","typeGuard":null,"tryCatchPattern":"try { aeron.addSubscription(channel, streamId, handler, unavailableHandler); } catch (InvalidChannelException e) { if (e.getMessage().contains(\"option conflicts\")) { log.error(\"align reliable option with existing subscription: {}\", e.getMessage()); } throw e; }","preventionTips":["Centralize subscription URI templates so reliable= is set in exactly one place","Document the reliable setting for each shared stream","Close conflicting subscriptions before re-adding with changed options","Search the codebase for all addSubscription calls on a stream when changing options"],"tags":["aeron","subscription","channel-config","conflict"],"backgroundTag":"conflicting-config-options","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}