{"record":{"id":"6c6fac0d5b686142","repo":"aeron-io/aeron","slug":"initial-term-id-must-be-a-valid-integer","errorCode":null,"errorMessage":"'initial-term-id' must be a valid integer","messagePattern":"'initial-term-id' must be a valid integer","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/ChannelUriStringBuilder.java","lineNumber":755,"sourceCode":"     * @see CommonContext#INITIAL_TERM_ID_PARAM_NAME\n     */\n    public ChannelUriStringBuilder initialTermId(final ChannelUri channelUri)\n    {\n        final String initialTermIdValue = channelUri.get(INITIAL_TERM_ID_PARAM_NAME);\n        if (null == initialTermIdValue)\n        {\n            initialTermId = null;\n            return this;\n        }\n        else\n        {\n            try\n            {\n                return initialTermId(Integer.valueOf(initialTermIdValue));\n            }\n            catch (final NumberFormatException ex)\n            {\n                throw new IllegalArgumentException(\"'initial-term-id' must be a valid integer\", ex);\n            }\n        }\n    }\n\n    /**\n     * the initial term id at which a publication will start.\n     *\n     * @return the initial term id at which a publication will start.\n     * @see CommonContext#INITIAL_TERM_ID_PARAM_NAME\n     */\n    public Integer initialTermId()\n    {\n        return initialTermId;\n    }\n\n    /**\n     * Set the current term id at which a publication will start. This when combined with the initial term can\n     * establish a starting position.","sourceCodeStart":737,"sourceCodeEnd":773,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/ChannelUriStringBuilder.java#L737-L773","documentation":"When building from a parsed channel URI, ChannelUriStringBuilder.initialTermId() reads the 'initial-term-id' parameter and converts it with Integer.valueOf. If the string is not a valid 32-bit integer (empty, alphabetic, out of int range), it is rethrown as IllegalArgumentException with this message and the NumberFormatException as cause. This indicates a malformed URI parameter value.","triggerScenarios":"Passing a channel URI whose initial-term-id value is non-numeric, e.g. 'aeron:udp?...|initial-term-id=abc' or 'initial-term-id=99999999999' (exceeds int range).","commonSituations":"Manual URI editing with typos; generating URIs with long/64-bit term IDs from a different system; string concatenation bugs producing empty or partially formatted values.","solutions":["Fix the initial-term-id value in the URI to a signed 32-bit integer (e.g. -123456789 or 42)","If the value is computed as a long, mask or cast to int before formatting: (int)initialTermId","Validate with Integer.parseInt(value) inside try-catch before building the URI"],"exampleFix":"// before\nString uri = \"aeron:udp?endpoint=localhost:40456|initial-term-id=1x0\";\n// after\nString uri = \"aeron:udp?endpoint=localhost:40456|initial-term-id=100\";","handlingStrategy":"validation","validationCode":"try { Integer.parseInt(initialTermIdValue); } catch (NumberFormatException e) { throw new IllegalArgumentException(\"invalid initial-term-id: \" + initialTermIdValue); }","typeGuard":null,"tryCatchPattern":"try { builder.initialTermId(uriValue); } catch (IllegalArgumentException e) { /* handle NumberFormatException cause */ }","preventionTips":["Cast long term ids to int before formatting into URIs","Never build URIs by raw string concatenation of numeric fields; use ChannelUriStringBuilder","Validate URI parameters with Integer.parseInt before use"],"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"}