{"record":{"id":"2cbb36b34bd72cfc","repo":"aeron-io/aeron","slug":"term-id-must-be-a-valid-integer","errorCode":null,"errorMessage":"'term-id' must be a valid integer","messagePattern":"'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":808,"sourceCode":"     * @see CommonContext#TERM_ID_PARAM_NAME\n     */\n    public ChannelUriStringBuilder termId(final ChannelUri channelUri)\n    {\n        final String termIdValue = channelUri.get(TERM_ID_PARAM_NAME);\n        if (null == termIdValue)\n        {\n            termId = null;\n            return this;\n        }\n        else\n        {\n            try\n            {\n                return termId(Integer.valueOf(termIdValue));\n            }\n            catch (final NumberFormatException ex)\n            {\n                throw new IllegalArgumentException(\"'term-id' must be a valid integer\", ex);\n            }\n        }\n    }\n\n    /**\n     * Get the current term id at which a publication will start.\n     *\n     * @return the current term id at which a publication will start.\n     * @see CommonContext#TERM_ID_PARAM_NAME\n     */\n    public Integer termId()\n    {\n        return termId;\n    }\n\n    /**\n     * Set the offset within a term at which a publication will start. This when combined with the term id can establish\n     * a starting position.","sourceCodeStart":790,"sourceCodeEnd":826,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/ChannelUriStringBuilder.java#L790-L826","documentation":"ChannelUriStringBuilder.termId() converts the 'term-id' URI parameter with Integer.valueOf and wraps any NumberFormatException as IllegalArgumentException with this message. The 'term-id' must be a valid signed 32-bit integer because term IDs are int values in Aeron's positioning scheme.","triggerScenarios":"Passing a channel URI with a non-integer 'term-id' value, e.g. '|term-id=abc', '|term-id=3.5', or a value beyond Integer.MAX_VALUE such as a 64-bit id.","commonSituations":"Copy-pasted URIs from logs where the term id was printed as a long; template URIs with placeholder text not substituted; computed ids wider than int.","solutions":["Correct the term-id value to a signed 32-bit integer in the URI","If the id is a long, convert with (int)termId or Math.toIntExact plus masking before formatting","Pre-validate the string with Integer.parseInt in a try-catch before constructing the URI"],"exampleFix":"// before\nbuilder.termId(\"5294967296\"); // exceeds int range\n// after\nbuilder.termId(\"1000000000\");","handlingStrategy":"validation","validationCode":"try { Integer.parseInt(termIdValue); } catch (NumberFormatException e) { throw new IllegalArgumentException(\"invalid term-id: \" + termIdValue); }","typeGuard":null,"tryCatchPattern":"try { builder.termId(uriValue); } catch (IllegalArgumentException e) { log.error(\"term-id must be int32\", e); }","preventionTips":["Keep term ids as int in your code, not long","Use ChannelUriStringBuilder rather than string concatenation for URIs","Reject non-numeric values at configuration load time"],"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"}