{"record":{"id":"e319d267c2a888dc","repo":"aeron-io/aeron","slug":"term-offset-must-be-a-valid-integer","errorCode":null,"errorMessage":"'term-offset' must be a valid integer","messagePattern":"'term-offset' must be a valid integer","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/ChannelUriStringBuilder.java","lineNumber":874,"sourceCode":"     * @see CommonContext#TERM_OFFSET_PARAM_NAME\n     */\n    public ChannelUriStringBuilder termOffset(final ChannelUri channelUri)\n    {\n        final String termOffsetValue = channelUri.get(TERM_OFFSET_PARAM_NAME);\n        if (null == termOffsetValue)\n        {\n            termOffset = null;\n            return this;\n        }\n        else\n        {\n            try\n            {\n                return termOffset(Integer.valueOf(termOffsetValue));\n            }\n            catch (final NumberFormatException ex)\n            {\n                throw new IllegalArgumentException(\"'term-offset' must be a valid integer\", ex);\n            }\n        }\n    }\n\n    /**\n     * Get the offset within a term at which a publication will start.\n     *\n     * @return the offset within a term at which a publication will start.\n     * @see CommonContext#TERM_OFFSET_PARAM_NAME\n     */\n    public Integer termOffset()\n    {\n        return termOffset;\n    }\n\n    /**\n     * Set the session id for a publication or restricted subscription.\n     *","sourceCodeStart":856,"sourceCodeEnd":892,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/ChannelUriStringBuilder.java#L856-L892","documentation":"ChannelUriStringBuilder.termOffset(String) parses the 'term-offset' URI parameter with Integer.valueOf and converts NumberFormatException into this IllegalArgumentException. It indicates the 'term-offset' value in the channel URI is not a valid signed 32-bit integer, independent of the later range/alignment checks.","triggerScenarios":"Passing a URI like 'aeron:udp?...|term-offset=abc', 'term-offset=1.5', 'term-offset=', or a value above Integer.MAX_VALUE.","commonSituations":"Template URIs with unsubstituted placeholders; copy/paste from documentation where the value was example text; formatting bugs producing decimal or empty strings.","solutions":["Fix the term-offset value in the URI to a plain integer (e.g. term-offset=1024)","Validate the string with Integer.parseInt before use and surface a clearer error","Remember additional constraints: after parsing, the value must also be in 0..1g and a multiple of 32"],"exampleFix":"// before\nString uri = \"aeron:udp?endpoint=h:40456|term-offset=0x400\"; // hex not parsed\n// after\nString uri = \"aeron:udp?endpoint=h:40456|term-offset=1024\";","handlingStrategy":"validation","validationCode":"try { Integer.parseInt(termOffsetValue); } catch (NumberFormatException e) { throw new IllegalArgumentException(\"invalid term-offset: \" + termOffsetValue); }","typeGuard":null,"tryCatchPattern":"try { builder.termOffset(uriValue); } catch (IllegalArgumentException e) { log.error(\"term-offset must be int32\", e); }","preventionTips":["Store numeric URI parameters as typed fields, not strings","Validate all numeric URI parameters at config load time","Use ChannelUriStringBuilder to assemble URIs instead of templates"],"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"}