{"record":{"id":"751fef1416af05e7","repo":"aeron-io/aeron","slug":"invalid-channel-ex","errorCode":null,"errorMessage":"invalid channel: ${ex}","messagePattern":"invalid channel: (.+?)","errorType":"exception","errorClass":"InvalidChannelException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/DriverConductor.java","lineNumber":1219,"sourceCode":"                }\n            }\n        }\n        else\n        {\n            timeOfLastToDriverPositionChangeNs = nowNs;\n            lastCommandConsumerPosition = consumerPosition;\n        }\n    }\n\n    private static ChannelUri parseUri(final String channel)\n    {\n        try\n        {\n            return ChannelUri.parse(channel);\n        }\n        catch (final Exception ex)\n        {\n            throw new InvalidChannelException(ex);\n        }\n    }\n\n    private record StreamInterest(boolean sparse, boolean reliable, boolean multicastSemantics)\n    {\n    }\n\n    private StreamInterest findSubscribers(\n        final ReceiveChannelEndpoint channelEndpoint, final int sessionId, final int streamId, final short flags)\n    {\n        if (ChannelEndpointStatus.ACTIVE != channelEndpoint.status())\n        {\n            return null;\n        }\n\n        long regId = Long.MAX_VALUE;\n        boolean hasSubscribers = false;\n        boolean sparse = false, reliable = false, multicastSemantics = false;","sourceCodeStart":1201,"sourceCodeEnd":1237,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/DriverConductor.java#L1201-L1237","documentation":"ChannelUri.parse failed to parse the given channel URI string, so the driver wraps the underlying exception in InvalidChannelException and reports the channel as invalid. Aeron channel URIs must follow the aeron: transport schema with valid params (e.g. aeron:udp?endpoint=host:port). Malformed syntax, unknown transport, or illegal parameters make the subscription/publication request unprocessable.","triggerScenarios":"Adding a subscription or publication with a malformed channel string such as missing 'aeron:udp'/'aeron:ipc' prefix, unbalanced quoting, bad endpoint syntax, or unknown params that the URI parser rejects; parse happens in DriverConductor when validating the channel before creating the endpoint.","commonSituations":"Typo in channel URI (e.g. 'aeron:up?...' or missing '?'); building the URI by string concatenation with a null or empty host/port; copying a URI from docs with placeholders left in; platform-specific multicast address typos.","solutions":["Validate the URI with ChannelUri.parse(channel) in a try/catch before sending the request to the driver","Use ChannelUriStringBuilder to construct channels instead of hand-built strings","Print/log the exact channel string passed to addSubscription/addPublication and check prefix is 'aeron:udp' or 'aeron:ipc'","Catch InvalidChannelException around client add* calls and surface a clear config error to the operator"],"exampleFix":"// before\nString channel = \"aeron:udp?endpoint=\" + host + \":\"; // port missing -> InvalidChannelException\nsubscription = aeron.addSubscription(channel, streamId);\n// after\nString channel = new ChannelUriStringBuilder()\n    .media(\"udp\").endpoint(host + \":\" + port).build();\nsubscription = aeron.addSubscription(channel, streamId);","handlingStrategy":"validation","validationCode":"try\n{\n    ChannelUri.parse(channel);\n}\ncatch (Exception ex)\n{\n    throw new IllegalArgumentException(\"Bad channel URI: \" + channel, ex);\n}","typeGuard":"static boolean isValidChannel(String channel)\n{\n    try { ChannelUri.parse(channel); return true; }\n    catch (Exception ex) { return false; }\n}","tryCatchPattern":"try\n{\n    subscription = aeron.addSubscription(channel, streamId);\n}\ncatch (InvalidChannelException ex)\n{\n    log.error(\"Invalid channel URI '{}': {}\", channel, ex.getMessage());\n}","preventionTips":["Build channels with ChannelUriStringBuilder instead of string concatenation","Assert channel strings start with aeron:udp or aeron:ipc in config loading","Unit-test channel construction so malformed URIs fail before runtime"],"tags":["aeron","uri","configuration"],"backgroundTag":"invalid-url-format","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"}