{"record":{"id":"81cb8f2b4e148b35","repo":"aeron-io/aeron","slug":"gtag-must-be-a-valid-long-value","errorCode":null,"errorMessage":"'gtag' must be a valid long value","messagePattern":"'gtag' must be a valid long value","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/ChannelUriStringBuilder.java","lineNumber":1510,"sourceCode":"     * @see CommonContext#GROUP_TAG_PARAM_NAME\n     */\n    public ChannelUriStringBuilder groupTag(final ChannelUri channelUri)\n    {\n        final String groupTagValue = channelUri.get(GROUP_TAG_PARAM_NAME);\n        if (null == groupTagValue)\n        {\n            groupTag = null;\n            return this;\n        }\n        else\n        {\n            try\n            {\n                return groupTag(Long.valueOf(groupTagValue));\n            }\n            catch (final NumberFormatException ex)\n            {\n                throw new IllegalArgumentException(\"'gtag' must be a valid long value\", ex);\n            }\n        }\n    }\n\n    /**\n     * Get the group tag (gtag) to be sent in SMs (Status Messages).\n     *\n     * @return receiver tag to be sent in SMs.\n     * @see CommonContext#GROUP_TAG_PARAM_NAME\n     */\n    public Long groupTag()\n    {\n        return groupTag;\n    }\n\n    /**\n     * Set the subscription semantics for if a stream should be rejoined after going unavailable.\n     *","sourceCodeStart":1492,"sourceCodeEnd":1528,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/ChannelUriStringBuilder.java#L1492-L1528","documentation":"ChannelUriStringBuilder parses the 'gtag' (group tag) URI parameter with Long.valueOf and converts NumberFormatException into this IllegalArgumentException. The group tag is sent in Status Messages and is a 64-bit long, so the URI value must be a valid signed long integer.","triggerScenarios":"A channel URI containing 'gtag=abc', 'gtag=12.5', or 'gtag=9223372036854775808' (above Long.MAX_VALUE), processed by the builder's URI-initialisation path.","commonSituations":"Placeholder text left in URI templates; formatting a BigInteger or unsigned value that overflows long; copy/paste errors from logs.","solutions":["Correct the gtag value in the URI to a signed 64-bit long (e.g. gtag=123456789)","Clamp or wrap over-wide values into long range before formatting","Pre-validate with Long.parseLong(value) in a try-catch before building"],"exampleFix":"// before\nString uri = \"aeron:udp?endpoint=h:40456|gtag=<gt>\"; // placeholder left in\n// after\nString uri = \"aeron:udp?endpoint=h:40456|gtag=1001\";","handlingStrategy":"validation","validationCode":"try { Long.parseLong(gtagValue); } catch (NumberFormatException e) { throw new IllegalArgumentException(\"invalid gtag: \" + gtagValue); }","typeGuard":null,"tryCatchPattern":"try { builder.groupTag(gtagStr); } catch (IllegalArgumentException e) { log.error(\"gtag must be long\", e); }","preventionTips":["Keep gtag values as long primitives in your code","Substitute URI template placeholders programmatically and assert no '<' or '>' remain","Validate all URI numeric fields when loading configuration"],"tags":["aeron","uri-validation","number-format"],"backgroundTag":"invalid-argument-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"}