{"record":{"id":"78f19e0ee575919b","repo":"aeron-io/aeron","slug":"invalidchannelexception","errorCode":null,"errorMessage":"InvalidChannelException","messagePattern":"InvalidChannelException","errorType":"exception","errorClass":"InvalidChannelException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/media/UdpChannel.java","lineNumber":298,"sourceCode":"                    .remoteDataAddress(endpointAddress)\n                    .localControlAddress(localAddress)\n                    .localDataAddress(localAddress)\n                    .canonicalForm(canonicalise(null, localAddress, endpointVal, endpointAddress) + suffix);\n            }\n\n            context.channelReceiveTimestampOffset(\n                parseTimestampOffset(channelUri, CHANNEL_RECEIVE_TIMESTAMP_OFFSET_PARAM_NAME));\n            context.channelSendTimestampOffset(\n                parseTimestampOffset(channelUri, CHANNEL_SEND_TIMESTAMP_OFFSET_PARAM_NAME));\n\n            final Long groupTag = parseOptionalLong(channelUri, GROUP_TAG_PARAM_NAME);\n            context.groupTag(groupTag);\n\n            return new UdpChannel(context);\n        }\n        catch (final Exception ex)\n        {\n            throw new InvalidChannelException(ex);\n        }\n    }\n\n    private static int parseTimestampOffset(final ChannelUri channelUri, final String timestampOffsetParamName)\n    {\n        final String offsetStr = channelUri.get(timestampOffsetParamName);\n        if (null == offsetStr)\n        {\n            return Aeron.NULL_VALUE;\n        }\n        else if (RESERVED_OFFSET.equals(offsetStr))\n        {\n            return RESERVED_VALUE_MESSAGE_OFFSET;\n        }\n        else\n        {\n            try\n            {","sourceCodeStart":280,"sourceCodeEnd":316,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/media/UdpChannel.java#L280-L316","documentation":"A wrapper exception (InvalidChannelException) thrown from UdpChannel.parse for ANY exception raised while parsing or validating a channel URI, including address resolution failures and invalid parameters. The original cause is available via getCause().","triggerScenarios":"Any malformed or unresolvable channel URI passed to addSubscription/addPublication, e.g. unknown parameter names, unparseable addresses, invalid tags or control-mode combos.","commonSituations":"Mistyped channel URIs in configuration, dynamic channel construction from user input, version upgrades adding new parameter validation, unresolvable hostnames.","solutions":["Inspect ex.getCause() to find the underlying parse error","Validate the channel URI syntax (aeron:udp?param=value) before passing it to Aeron","Check parameter names against the Aeron version in use","Fix the specific root cause (hostname, numeric value, tag configuration)"],"exampleFix":"// before\nclient.addSubscription(uri, streamId); // uri malformed, NPE wraps into InvalidChannelException\n// after\nif (uri == null || !uri.startsWith(\"aeron:\")) throw new IllegalArgumentException(\"bad channel: \" + uri);\nclient.addSubscription(uri, streamId);","handlingStrategy":"try-catch","validationCode":"if (!uri.startsWith(\"aeron:udp\") && !uri.startsWith(\"aeron:ipc\")) throw new IllegalArgumentException(\"unsupported channel: \" + uri);","typeGuard":"static boolean isWellFormedAeronUri(String uri) { return uri != null && uri.matches(\"aeron:(udp|ipc)(\\\\?.*)?\"); }","tryCatchPattern":"try { return aeron.addPublication(uri, streamId); } catch (InvalidChannelException e) { throw new IllegalArgumentException(\"bad channel URI '\" + uri + \"': \" + e.getCause().getMessage(), e); }","preventionTips":["Always inspect getCause() on InvalidChannelException","Centralize channel URI construction in one validated helper","Pin Aeron versions and review changelogs for new parameter validation","Never build URIs from unvalidated user input"],"tags":["aeron","channel-uri","validation"],"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-19T12:17:13.211Z"}