aeron-io/aeron · error · IllegalArgumentException

channelReceiveTimestampOffset must be a number or the value

Error message

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

What it means

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.

Solutions

1. Provide a plain integer offset (byte offset into the message header).
2. Use the literal keyword 'reserved' for the reserved header field.
3. Trim the value and confirm your config template substitutes a valid integer or 'reserved'.

Example fix

// before
builder.channelReceiveTimestampOffset("RESERVED");
// after
builder.channelReceiveTimestampOffset("reserved"); // lowercase, or an integer like "0"

void checkChannelRcvOffset(String value) {
    if (value == null) return;
    if (!"reserved".equals(value.trim())) {
        Integer.parseInt(value.trim());
    }
}

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

try {
    builder.channelReceiveTimestampOffset(offset);
} catch (IllegalArgumentException e) {
    log.warn("Invalid channel_rcv_timestamp_offset '{}'", offset, e);
    // omit the parameter or fall back to 'reserved'
}

When it happens

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

Common situations: Typos in the reserved keyword (e.g. 'RESERVED' or 'reserved '); unit suffixes ('32B'); environment-substituted config values left empty or placeholder-laden.

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

• mediaReceiveTimestampOffset must be a number or the value
• channelSendTimestampOffset must be a number or the value
• Aeron URIs must start with 'aeron:', found
• responseCorrelationId must be a number greater than or…
• invalid position

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

Appendix: source

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

     * Offset into a message to store the channel 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 doesn't represent an int or the 'reserved' value.
     * @see CommonContext#CHANNEL_RECEIVE_TIMESTAMP_OFFSET_PARAM_NAME
     */
    public ChannelUriStringBuilder channelReceiveTimestampOffset(final String timestampOffset)
    {
        if (null != timestampOffset && !RESERVED_OFFSET.equals(timestampOffset))
        {
            try
            {
                Integer.parseInt(timestampOffset);
            }
            catch (final NumberFormatException ex)
            {
                throw new IllegalArgumentException(
                    "channelReceiveTimestampOffset must be a number or the value '" + RESERVED_OFFSET + "' found: " +
                    timestampOffset);
            }
        }

        this.channelReceiveTimestampOffset = timestampOffset;
        return this;
    }

    /**
     * Offset into a message to store the channel 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 receiveTimestampOffset from.
     * @return this for a fluent API.
     * @see CommonContext#CHANNEL_RECEIVE_TIMESTAMP_OFFSET_PARAM_NAME
     */
    public ChannelUriStringBuilder channelReceiveTimestampOffset(final ChannelUri channelUri)

View on GitHub (pinned to 6d60124e15)