aeron-io/aeron · error · IllegalArgumentException

mediaReceiveTimestampOffset must be a number or the value

Error message

mediaReceiveTimestampOffset must be a number or the value '${RESERVED_OFFSET}' found: ${timestampOffset}

What it means

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.

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.

Example fix

// before
builder.mediaReceiveTimestampOffset("64ns");
// after
builder.mediaReceiveTimestampOffset("64"); // or "reserved"

Defensive patterns

Strategy: validation

Validate before calling

void checkTimestampOffset(String value) {
    if (value == null) return;
    if (!"reserved".equals(value)) {
        Integer.parseInt(value.trim()); // throws NumberFormatException if invalid
    }
}

Type guard

boolean isValidTimestampOffset(String value) {
    if (value == null) return true;
    value = value.trim();
    return "reserved".equals(value) || value.matches("-?\\d+");
}

Try / catch

try {
    builder.mediaReceiveTimestampOffset(offset);
} catch (IllegalArgumentException e) {
    log.warn("Invalid media_rcv_timestamp_offset '{}', defaulting", offset, e);
    // omit the parameter
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

AI-assisted analysis of aeron-io/aeron@6d60124e15 (2026-09-12). Data as JSON: /api/errors/8996a345f1684071. Report an issue: GitHub.

Appendix: source

Thrown at aeron-client/src/main/java/io/aeron/ChannelUriStringBuilder.java:1834

     * Offset into a message to store the media receive timestamp. May also be the special value 'reserved' which means
     * to store the timestamp in the reserved value field.
     *
     * @param timestampOffset to use as the offset.
     * @return this for a fluent API.
     * @throws IllegalArgumentException if the string is not null and doesn't represent an int or the 'reserved' value.
     * @see CommonContext#MEDIA_RCV_TIMESTAMP_OFFSET_PARAM_NAME
     */
    public ChannelUriStringBuilder mediaReceiveTimestampOffset(final String timestampOffset)
    {
        if (null != timestampOffset && !RESERVED_OFFSET.equals(timestampOffset))
        {
            try
            {
                Integer.parseInt(timestampOffset);
            }
            catch (final NumberFormatException ex)
            {
                throw new IllegalArgumentException(
                    "mediaReceiveTimestampOffset must be a number or the value '" + RESERVED_OFFSET + "' found: " +
                    timestampOffset);
            }
        }

        this.mediaReceiveTimestampOffset = timestampOffset;
        return this;
    }

    /**
     * Offset into a message to store the media receive timestamp. May also be the special value 'reserved' which means
     * to store the timestamp in the reserved value field.
     *
     * @param channelUri the existing URI to extract the mediaReceiveTimestampOffset from
     * @return this for a fluent API.
     * @see CommonContext#MEDIA_RCV_TIMESTAMP_OFFSET_PARAM_NAME
     */
    public ChannelUriStringBuilder mediaReceiveTimestampOffset(final ChannelUri channelUri)

View on GitHub (pinned to 6d60124e15)