{"record":{"id":"8cc987abc2cb8562","repo":"aeron-io/aeron","slug":"aeron-uris-must-start-with-aeron-found-uri","errorCode":null,"errorMessage":"Aeron URIs must start with 'aeron:', found: <uri>","messagePattern":"Aeron URIs must start with 'aeron:', found: <uri>","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/ChannelUri.java","lineNumber":396,"sourceCode":"            throw new IllegalArgumentException(\"URI length (\" + length + \") exceeds max supported length (\" +\n                MAX_URI_LENGTH + \"): \" + uri.subSequence(0, MAX_URI_LENGTH));\n        }\n\n        int position = 0;\n        final String prefix;\n        if (startsWith(uri, 0, SPY_PREFIX))\n        {\n            prefix = SPY_QUALIFIER;\n            position = SPY_PREFIX.length();\n        }\n        else\n        {\n            prefix = \"\";\n        }\n\n        if (!startsWith(uri, position, AERON_PREFIX))\n        {\n            throw new IllegalArgumentException(\"Aeron URIs must start with 'aeron:', found: \" + uri);\n        }\n        else\n        {\n            position += AERON_PREFIX.length();\n        }\n\n        final StringBuilder builder = new StringBuilder();\n        final Object2ObjectHashMap<String, String> params = new Object2ObjectHashMap<>();\n        String media = null;\n        String key = null;\n\n        State state = State.MEDIA;\n        for (int i = position; i < length; i++)\n        {\n            final char c = uri.charAt(i);\n            switch (state)\n            {\n                case MEDIA:","sourceCodeStart":378,"sourceCodeEnd":414,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/ChannelUri.java#L378-L414","documentation":"Every Aeron channel URI must begin with the 'aeron:' scheme prefix (optionally after the 'aeron-spy:' spy prefix). ChannelUri.parse throws IllegalArgumentException when the URI at the current position lacks this prefix, echoing the full offending string.","triggerScenarios":"Calling ChannelUri.parse with a string missing 'aeron:' — e.g. bare 'udp://host:port', 'localhost:40456', an empty/whitespace string, or a typo like 'aeron-udp:'.","commonSituations":"Reusing socket-style URIs from other libraries; concatenating transport onto the URI in the wrong place; config where the scheme got stripped by a properties loader; users writing 'aeron=udp://...' instead of 'aeron:udp://...'.","solutions":["Ensure the channel string starts with 'aeron:', e.g. 'aeron:udp?endpoint=localhost:40456'.","If you only have a transport string like 'udp?endpoint=...', prepend the scheme: \"aeron:\" + transport.","Validate/normalize channel configuration at startup and fail fast with a clear message.","Check for scheme-stripping in config handling (properties parsing, env vars, YAML quoting)."],"exampleFix":"// before\nString channel = \"udp?endpoint=224.0.1.1:40456\";\n// after\nString channel = \"aeron:udp?endpoint=224.0.1.1:40456\";","handlingStrategy":"validation","validationCode":"if (channel == null || !(channel.startsWith(\"aeron:\") || channel.startsWith(\"aeron-spy:\"))) {\n    throw new ConfigException(\"channel must start with aeron: : \" + channel);\n}","typeGuard":null,"tryCatchPattern":"try {\n    ChannelUri uri = ChannelUri.parse(channel);\n} catch (IllegalArgumentException e) {\n    channel = \"aeron:\" + channel; // or fail fast with a clear message\n}","preventionTips":["Store full URIs including the scheme in config files","Watch for scheme-stripping by properties/YAML loaders","Normalize socket-style URIs to Aeron syntax in one helper"],"tags":["aeron","channel-uri","uri","format"],"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"}