{"record":{"id":"9bbb55d67989657b","repo":"aeron-io/aeron","slug":"invalid-prefix-prefix","errorCode":null,"errorMessage":"invalid prefix: ${prefix}","messagePattern":"invalid prefix: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/ChannelUriStringBuilder.java","lineNumber":260,"sourceCode":"                throw new IllegalArgumentException(\"termOffset=\" + termOffset + \" > termLength=\" + termLength);\n            }\n        }\n\n        return this;\n    }\n\n    /**\n     * Set the prefix for taking an additional action such as spying on an outgoing publication with \"aeron-spy\".\n     *\n     * @param prefix to be applied to the URI before the scheme.\n     * @return this for a fluent API.\n     * @see ChannelUri#SPY_QUALIFIER\n     */\n    public ChannelUriStringBuilder prefix(final String prefix)\n    {\n        if (null != prefix && !prefix.isEmpty() && !prefix.equals(SPY_QUALIFIER))\n        {\n            throw new IllegalArgumentException(\"invalid prefix: \" + prefix);\n        }\n\n        this.prefix = prefix;\n        return this;\n    }\n\n    /**\n     * Set the prefix value to be what is in the {@link ChannelUri}.\n     *\n     * @param channelUri to read the value from.\n     * @return this for a fluent API.\n     * @see ChannelUri#SPY_QUALIFIER\n     */\n    public ChannelUriStringBuilder prefix(final ChannelUri channelUri)\n    {\n        return prefix(channelUri.prefix());\n    }\n","sourceCodeStart":242,"sourceCodeEnd":278,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/ChannelUriStringBuilder.java#L242-L278","documentation":"Thrown by ChannelUriStringBuilder.prefix(String) when a non-empty prefix other than the spy qualifier is supplied. Aeron only supports 'aeron:' (implicit) and the 'aeron-spy:' prefix; anything else cannot form a valid channel URI.","triggerScenarios":"builder.prefix(\"udp:\") or any string other than \"aeron-spy:\" (ChannelUri.SPY_QUALIFIER) or null/empty.","commonSituations":"Trying to encode the transport in the prefix instead of media(); typo of the spy qualifier (e.g. \"aeron-spy\" without colon or \"spy:\"); carrying over a URI fragment parsed from another system.","solutions":["Use prefix(\"aeron-spy:\") only when spy semantics are intended; otherwise omit prefix entirely.","Move transport selection to media(\"udp\") or media(\"ipc\").","Strip or normalize the prefix before building if you received a full URI string."],"exampleFix":"// before\nbuilder.prefix(\"udp:\").media(\"udp\");\n// after\nbuilder.media(\"udp\");","handlingStrategy":"type-guard","validationCode":"if (prefix != null && !prefix.isEmpty() && !ChannelUri.SPY_QUALIFIER.equals(prefix)) { throw new IllegalArgumentException(\"invalid prefix: \" + prefix); }","typeGuard":"boolean isValidPrefix(String prefix) { return prefix == null || prefix.isEmpty() || ChannelUri.SPY_QUALIFIER.equals(prefix); }","tryCatchPattern":"try { builder.prefix(p); } catch (IllegalArgumentException e) { builder.prefix(null); /* fall back to default */ }","preventionTips":["Only ever pass ChannelUri.SPY_QUALIFIER or null to prefix()","Select transport via media(), not the prefix","Normalize full URIs through ChannelUri.parse before rebuilding"],"tags":["aeron","channel-uri","validation","uri"],"backgroundTag":"invalid-argument-value","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"}