{"record":{"id":"2bd6de2dc0e7fdb1","repo":"aeron-io/aeron","slug":"channelreceivetimestampoffset-must-be-a-number-or-the-value","errorCode":null,"errorMessage":"channelReceiveTimestampOffset must be a number or the value '${RESERVED_OFFSET}' found: ${timestampOffset}","messagePattern":"channelReceiveTimestampOffset 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":1889,"sourceCode":"     * Offset into a message to store the channel receive timestamp. May also be the special value 'reserved' which\n     * means 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 doesn't represent an int or the 'reserved' value.\n     * @see CommonContext#CHANNEL_RECEIVE_TIMESTAMP_OFFSET_PARAM_NAME\n     */\n    public ChannelUriStringBuilder channelReceiveTimestampOffset(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                    \"channelReceiveTimestampOffset must be a number or the value '\" + RESERVED_OFFSET + \"' found: \" +\n                    timestampOffset);\n            }\n        }\n\n        this.channelReceiveTimestampOffset = timestampOffset;\n        return this;\n    }\n\n    /**\n     * Offset into a message to store the channel receive timestamp. May also be the special value 'reserved' which\n     * means to store the timestamp in the reserved value field.\n     *\n     * @param channelUri the existing URI to extract the receiveTimestampOffset from.\n     * @return this for a fluent API.\n     * @see CommonContext#CHANNEL_RECEIVE_TIMESTAMP_OFFSET_PARAM_NAME\n     */\n    public ChannelUriStringBuilder channelReceiveTimestampOffset(final ChannelUri channelUri)","sourceCodeStart":1871,"sourceCodeEnd":1907,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/ChannelUriStringBuilder.java#L1871-L1907","documentation":"Thrown when parsing the channel_rcv_timestamp_offset channel URI parameter. The value must be an integer offset into the message header or the reserved keyword (\"reserved\"). Non-numeric values are rejected with this IllegalArgumentException so misconfiguration fails at URI-build time rather than at receive time.","triggerScenarios":"Building/parsing a channel URI with channel_rcv_timestamp_offset set to a non-integer string other than 'reserved', e.g. channel_rcv_timestamp_offset=auto.","commonSituations":"Typos in the reserved keyword (e.g. 'RESERVED' or 'reserved '); unit suffixes ('32B'); environment-substituted config values left empty or placeholder-laden.","solutions":["Provide a plain integer offset (byte offset into the message header).","Use the literal keyword 'reserved' for the reserved header field.","Trim the value and confirm your config template substitutes a valid integer or 'reserved'."],"exampleFix":"// before\nbuilder.channelReceiveTimestampOffset(\"RESERVED\");\n// after\nbuilder.channelReceiveTimestampOffset(\"reserved\"); // lowercase, or an integer like \"0\"","handlingStrategy":"validation","validationCode":"void checkChannelRcvOffset(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.channelReceiveTimestampOffset(offset);\n} catch (IllegalArgumentException e) {\n    log.warn(\"Invalid channel_rcv_timestamp_offset '{}'\", offset, e);\n    // omit the parameter or fall back to 'reserved'\n}","preventionTips":["Use exact lowercase 'reserved' — the check is case-sensitive via Integer.parseInt fallback.","Verify templated configs substitute real integers or 'reserved', never placeholders.","Trim values before passing them in."],"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-15T23:17:13.987Z"}