{"record":{"id":"c0f5efe9033aff0d","repo":"aeron-io/aeron","slug":"ttl-not-in-range-0-255-ttl","errorCode":null,"errorMessage":"TTL not in range 0-255: ${ttl}","messagePattern":"TTL not in range 0-255: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/ChannelUriStringBuilder.java","lineNumber":550,"sourceCode":"public ChannelUriStringBuilder ttl(final Integer ttl)\n{\n    if (null != ttl && (ttl < 0 || ttl > 255))\n    {\n        throw new IllegalArgumentException(\"TTL not in range 0-255: \" + ttl);\n    }\n\n    this.ttl = ttl;\n    return this;\n}","sourceCodeStart":532,"sourceCodeEnd":568,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/ChannelUriStringBuilder.java#L532-L568","documentation":"Input validation guard in the fluent builder's ttl(Integer) setter. The ttl sets the Time To Live (hop count) for multicast datagrams, which must fit in a single unsigned byte (0-255). The exception fires when the caller supplies a null-checked non-null ttl value below 0 or above 255, rejecting the builder configuration before the value is stored for use in the channel URI's ttl= parameter.","triggerScenarios":"builder.ttl(256), builder.ttl(-1), or passing a parsed config value without range checking.","commonSituations":"Using OS defaults larger than 255; sign errors when reading config; computing TTL as a millisecond value instead of hop count.","solutions":["Clamp or validate the value to [0, 255] before calling ttl().","Use a typical multicast TTL such as 1-16 depending on network scope.","Omit ttl() if the default is acceptable."],"exampleFix":"// before\nbuilder.ttl(512);\n// after\nbuilder.ttl(Math.min(255, Math.max(0, configuredTtl)));","handlingStrategy":"validation","validationCode":"if (ttl != null && (ttl < 0 || ttl > 255)) { throw new IllegalArgumentException(\"TTL not in range 0-255: \" + ttl); }","typeGuard":"boolean isValidTtl(Integer ttl) { return ttl == null || (ttl >= 0 && ttl <= 255); }","tryCatchPattern":"try { builder.ttl(t); } catch (IllegalArgumentException e) { builder.ttl(1); }","preventionTips":["Clamp config values to [0,255] at load time","Remember TTL is hop count, not milliseconds","Use small TTLs (1-16) for multicast scoping"],"tags":["aeron","channel-uri","network","validation"],"backgroundTag":"value-out-of-range","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"}