{"record":{"id":"44d0bebe53422c6e","repo":"aeron-io/aeron","slug":"session-id-must-be-a-valid-integer","errorCode":null,"errorMessage":"'session-id' must be a valid integer","messagePattern":"'session-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":928,"sourceCode":"     */\n    public ChannelUriStringBuilder sessionId(final String sessionIdStr)\n    {\n        if (null != sessionIdStr)\n        {\n            if (ChannelUri.isTagged(sessionIdStr))\n            {\n                taggedSessionId(ChannelUri.getTag(sessionIdStr));\n            }\n            else\n            {\n                isSessionIdTagged(false);\n                try\n                {\n                    sessionId(Integer.valueOf(sessionIdStr));\n                }\n                catch (final NumberFormatException ex)\n                {\n                    throw new IllegalArgumentException(\"'session-id' must be a valid integer\", ex);\n                }\n            }\n        }\n        else\n        {\n            sessionId((Integer)null);\n        }\n\n        return this;\n    }\n\n    /**\n     * Set the session id for a publication or restricted subscription as a tag referenced value.\n     *\n     * @param sessionId for the publication or a restricted subscription.\n     * @return this for a fluent API.\n     * @see CommonContext#SESSION_ID_PARAM_NAME\n     */","sourceCodeStart":910,"sourceCodeEnd":946,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/ChannelUriStringBuilder.java#L910-L946","documentation":"When initializing from a channel URI, the builder parses the 'session-id' parameter with Integer.valueOf and wraps NumberFormatException as this IllegalArgumentException. Session ids are 32-bit ints in Aeron, so the URI value must be a valid signed integer (negative values are allowed for sparse session ids).","triggerScenarios":"A channel URI containing 'session-id=abc', 'session-id=12345678901', or an empty value, passed to ChannelUriStringBuilder.validate()/initialiseFromUri.","commonSituations":"Hand-edited URIs; generating session ids as longs and concatenating without casting; placeholder text left in configuration templates.","solutions":["Correct the session-id value in the URI to a signed 32-bit integer","Cast a long session id to int before formatting: (int)sessionId","Pre-validate the string with Integer.parseInt in a try-catch"],"exampleFix":"// before\nString uri = \"aeron:udp?endpoint=h:40456|session-id=42L\"; // suffix not accepted\n// after\nString uri = \"aeron:udp?endpoint=h:40456|session-id=42\";","handlingStrategy":"validation","validationCode":"try { Integer.parseInt(sessionIdValue); } catch (NumberFormatException e) { throw new IllegalArgumentException(\"invalid session-id: \" + sessionIdValue); }","typeGuard":null,"tryCatchPattern":"try { builder.sessionId(sessionIdStr); } catch (IllegalArgumentException e) { /* regenerate or fix session id */ }","preventionTips":["Cast long session ids to int before URI formatting","Let Aeron auto-assign session ids instead of hardcoding them when possible","Use ChannelUriStringBuilder.sessionId(Integer) with typed values"],"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"}