aeron-io/aeron · error · IllegalArgumentException

channelSendTimestampOffset must be a number or the value

Error message

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

What it means

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.

Solutions

1. Provide a plain integer offset or the exact lowercase keyword 'reserved'.
2. To disable send timestamping, remove the parameter rather than passing a placeholder value.
3. Trim whitespace and validate the URI before constructing.

Example fix

// before
builder.channelSendTimestampOffset("none");
// after
builder.channelSendTimestampOffset("reserved"); // or omit the parameter entirely

void checkChannelSndOffset(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.channelSendTimestampOffset(offset);
} catch (IllegalArgumentException e) {
    log.warn("Invalid channel_snd_timestamp_offset '{}'", offset, e);
    // omit the parameter to disable send timestamping
}

When it happens

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

Common situations: Using 'none' or 'off' to disable send timestamps (not valid — omit the parameter instead); unit suffixes; case-mismatched reserved keyword.

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
• channelReceiveTimestampOffset 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/9c640a94fb3f64ef. Report an issue: GitHub.

Appendix: source

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

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

        this.channelSendTimestampOffset = timestampOffset;
        return this;
    }

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

View on GitHub (pinned to 6d60124e15)