{"record":{"id":"8996a345f1684071","repo":"aeron-io/aeron","slug":"mediareceivetimestampoffset-must-be-a-number-or-the-value","errorCode":null,"errorMessage":"mediaReceiveTimestampOffset must be a number or the value '${RESERVED_OFFSET}' found: ${timestampOffset}","messagePattern":"mediaReceiveTimestampOffset 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":1834,"sourceCode":"     * Offset into a message to store the media receive 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 and doesn't represent an int or the 'reserved' value.\n     * @see CommonContext#MEDIA_RCV_TIMESTAMP_OFFSET_PARAM_NAME\n     */\n    public ChannelUriStringBuilder mediaReceiveTimestampOffset(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                    \"mediaReceiveTimestampOffset must be a number or the value '\" + RESERVED_OFFSET + \"' found: \" +\n                    timestampOffset);\n            }\n        }\n\n        this.mediaReceiveTimestampOffset = timestampOffset;\n        return this;\n    }\n\n    /**\n     * Offset into a message to store the media receive 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 mediaReceiveTimestampOffset from\n     * @return this for a fluent API.\n     * @see CommonContext#MEDIA_RCV_TIMESTAMP_OFFSET_PARAM_NAME\n     */\n    public ChannelUriStringBuilder mediaReceiveTimestampOffset(final ChannelUri channelUri)","sourceCodeStart":1816,"sourceCodeEnd":1852,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/ChannelUriStringBuilder.java#L1816-L1852","documentation":"Thrown when parsing the media_rcv_timestamp_offset channel URI parameter. The value must either be the reserved keyword (RESERVED_OFFSET, i.e. \"reserved\") or parse as an integer offset into the message header. Anything else (non-numeric, units attached, empty) is rejected.","triggerScenarios":"Building/parsing a channel URI with media_rcv_timestamp_offset=abc, media_rcv_timestamp_offset=64b, or any non-integer string other than the reserved keyword.","commonSituations":"Appending unit suffixes ('64ns', '32B'); copying a value from a different field that used a keyword other than 'reserved'; whitespace or quotes leaking into the URI from config templates.","solutions":["Use a plain integer for the offset (e.g. media_rcv_timestamp_offset=32).","Use the exact reserved keyword 'reserved' if you want the reserved timestamp field.","Trim whitespace and remove quotes/unit suffixes from the parameter value before parsing the URI."],"exampleFix":"// before\nbuilder.mediaReceiveTimestampOffset(\"64ns\");\n// after\nbuilder.mediaReceiveTimestampOffset(\"64\"); // or \"reserved\"","handlingStrategy":"validation","validationCode":"void checkTimestampOffset(String value) {\n    if (value == null) return;\n    if (!\"reserved\".equals(value)) {\n        Integer.parseInt(value.trim()); // throws NumberFormatException if invalid\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.mediaReceiveTimestampOffset(offset);\n} catch (IllegalArgumentException e) {\n    log.warn(\"Invalid media_rcv_timestamp_offset '{}', defaulting\", offset, e);\n    // omit the parameter\n}","preventionTips":["Only pass integers or the exact lowercase keyword 'reserved'.","Trim whitespace and strip unit suffixes from config values before use.","Centralize URI parameter validation in one helper."],"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"}