{"record":{"id":"9c640a94fb3f64ef","repo":"aeron-io/aeron","slug":"channelsendtimestampoffset-must-be-a-number-or-the-value","errorCode":null,"errorMessage":"channelSendTimestampOffset must be a number or the value '${RESERVED_OFFSET}' found: ${timestampOffset}","messagePattern":"channelSendTimestampOffset must be a number or the value '(.+?)' found: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/ChannelUriStringBuilder.java","lineNumber":1931,"sourceCode":"     * Offset into a message to store the channel send timestamp. May also be the special value 'reserved' which means\n     * to store the timestamp in the reserved value field.\n     *\n     * @param timestampOffset to use as the offset.\n     * @return this for a fluent API.\n     * @throws IllegalArgumentException if the string is not null doesn't represent an int or the 'reserved' value.\n     * @see CommonContext#CHANNEL_SEND_TIMESTAMP_OFFSET_PARAM_NAME\n     */\n    public ChannelUriStringBuilder channelSendTimestampOffset(final String timestampOffset)\n    {\n        if (null != timestampOffset && !RESERVED_OFFSET.equals(timestampOffset))\n        {\n            try\n            {\n                Integer.parseInt(timestampOffset);\n            }\n            catch (final NumberFormatException ex)\n            {\n                throw new IllegalArgumentException(\n                    \"channelSendTimestampOffset must be a number or the value '\" + RESERVED_OFFSET + \"' found: \" +\n                        timestampOffset);\n            }\n        }\n\n        this.channelSendTimestampOffset = timestampOffset;\n        return this;\n    }\n\n    /**\n     * Offset into a message to store the channel send timestamp. May also be the special value 'reserved' which means\n     * to store the timestamp in the reserved value field.\n     *\n     * @param channelUri the existing URI to extract the channelSendTimestampOffset from.\n     * @return this for a fluent API.\n     * @see CommonContext#CHANNEL_SEND_TIMESTAMP_OFFSET_PARAM_NAME\n     */\n    public ChannelUriStringBuilder channelSendTimestampOffset(final ChannelUri channelUri)","sourceCodeStart":1913,"sourceCodeEnd":1949,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/ChannelUriStringBuilder.java#L1913-L1949","documentation":"Thrown when parsing the channel_snd_timestamp_offset channel URI parameter. The value must be an integer offset into the message header or the reserved keyword (\"reserved\"); anything else fails Integer.parseInt and triggers this error. Validation happens eagerly in ChannelUriStringBuilder.","triggerScenarios":"Building/parsing a channel URI with channel_snd_timestamp_offset set to a non-numeric string other than 'reserved', e.g. channel_snd_timestamp_offset=none.","commonSituations":"Using 'none' or 'off' to disable send timestamps (not valid — omit the parameter instead); unit suffixes; case-mismatched reserved keyword.","solutions":["Provide a plain integer offset or the exact lowercase keyword 'reserved'.","To disable send timestamping, remove the parameter rather than passing a placeholder value.","Trim whitespace and validate the URI before constructing."],"exampleFix":"// before\nbuilder.channelSendTimestampOffset(\"none\");\n// after\nbuilder.channelSendTimestampOffset(\"reserved\"); // or omit the parameter entirely","handlingStrategy":"validation","validationCode":"void checkChannelSndOffset(String value) {\n    if (value == null) return;\n    if (!\"reserved\".equals(value.trim())) {\n        Integer.parseInt(value.trim());\n    }\n}","typeGuard":"boolean isValidTimestampOffset(String value) {\n    if (value == null) return true;\n    value = value.trim();\n    return \"reserved\".equals(value) || value.matches(\"-?\\\\d+\");\n}","tryCatchPattern":"try {\n    builder.channelSendTimestampOffset(offset);\n} catch (IllegalArgumentException e) {\n    log.warn(\"Invalid channel_snd_timestamp_offset '{}'\", offset, e);\n    // omit the parameter to disable send timestamping\n}","preventionTips":["To disable send timestamps, omit the parameter — do not pass 'none'/'off'.","Use plain integers or exact 'reserved' keyword only.","Validate URI strings early (at config load), not at publication creation."],"tags":["aeron","channel-uri","timestamp","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-16T04:17:20.429Z"}