aeron-io/aeron · error · IllegalArgumentException

timestamp offset must be a valid integer or the 'reserved'…

Error message

timestamp offset must be a valid integer or the 'reserved' keyword

What it means

Thrown when a channel URI's timestamp offset parameter (e.g. sesion-name-tagged channels' 'smdc-timestamp-offset' style params) is neither the keyword 'reserved' nor a parseable integer. Aeron requires an int offset or 'reserved'.

Solutions

1. Set the parameter to a valid integer (byte offset) or the literal string 'reserved'
2. Remove the parameter entirely if no timestamp offset is wanted
3. Check for unsubstituted template variables in the channel URI

Example fix

// before
"aeron:udp?endpoint=...|ts-offset=auto"
// after
"aeron:udp?endpoint=...|ts-offset=reserved"

String v = uri.getParam("ts-offset"); if (v != null && !v.equals("reserved") && !v.matches("-?\\d+")) throw new IllegalArgumentException("ts-offset must be int or 'reserved'");

static boolean isValidTimestampOffset(String v) { return v == null || v.equals("reserved") || v.matches("-?\\d+"); }

try { parseTimestampOffset(uri); } catch (IllegalArgumentException e) { log.warn("bad ts-offset in {}: {}", uri, e.getMessage()); }

When it happens

Trigger: Setting a timestamp offset parameter to a non-numeric string such as 'auto' or '5x', or an empty value.

Common situations: Copy-pasted config with wrong units or placeholder text, template variables left unsubstituted, confusion between offset and size parameters.

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

• Aeron URIs must start with 'aeron:', found
• channelReceiveTimestampOffset must be a number or the value
• channelSendTimestampOffset must be a number or the value
• destinations must not contain the key
• difference greater than 2^31 - 1: termId=

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

Appendix: source

Thrown at aeron-driver/src/main/java/io/aeron/driver/media/UdpChannel.java:321

    {
        final String offsetStr = channelUri.get(timestampOffsetParamName);
        if (null == offsetStr)
        {
            return Aeron.NULL_VALUE;
        }
        else if (RESERVED_OFFSET.equals(offsetStr))
        {
            return RESERVED_VALUE_MESSAGE_OFFSET;
        }
        else
        {
            try
            {
                return Integer.parseInt(offsetStr);
            }
            catch (final NumberFormatException ex)
            {
                throw new IllegalArgumentException(
                    "timestamp offset must be a valid integer or the 'reserved' keyword", ex);
            }
        }
    }

    private static Long parseOptionalLong(final ChannelUri channelUri, final String paramName)
    {
        final String longAsString = channelUri.get(paramName);
        if (null == longAsString)
        {
            return null;
        }

        try
        {
            return Long.valueOf(longAsString);
        }
        catch (final NumberFormatException ex)

View on GitHub (pinned to 6d60124e15)