aeron-io/aeron · error · IllegalArgumentException

'gtag' must be a valid long value

Error message

'gtag' must be a valid long value

What it means

ChannelUriStringBuilder parses the 'gtag' (group tag) URI parameter with Long.valueOf and converts NumberFormatException into this IllegalArgumentException. The group tag is sent in Status Messages and is a 64-bit long, so the URI value must be a valid signed long integer.

Solutions

1. Correct the gtag value in the URI to a signed 64-bit long (e.g. gtag=123456789)
2. Clamp or wrap over-wide values into long range before formatting
3. Pre-validate with Long.parseLong(value) in a try-catch before building

Example fix

// before
String uri = "aeron:udp?endpoint=h:40456|gtag=<gt>"; // placeholder left in
// after
String uri = "aeron:udp?endpoint=h:40456|gtag=1001";

try { Long.parseLong(gtagValue); } catch (NumberFormatException e) { throw new IllegalArgumentException("invalid gtag: " + gtagValue); }

try { builder.groupTag(gtagStr); } catch (IllegalArgumentException e) { log.error("gtag must be long", e); }

When it happens

Trigger: A channel URI containing 'gtag=abc', 'gtag=12.5', or 'gtag=9223372036854775808' (above Long.MAX_VALUE), processed by the builder's URI-initialisation path.

Common situations: Placeholder text left in URI templates; formatting a BigInteger or unsigned value that overflows long; copy/paste errors from logs.

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

• 'initial-term-id' must be a valid integer
• 'term-id' must be a valid integer
• 'term-offset' must be a valid integer
• 'session-id' must be a valid integer
• 'ttl' must be a value integer

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

Appendix: source

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

     * @see CommonContext#GROUP_TAG_PARAM_NAME
     */
    public ChannelUriStringBuilder groupTag(final ChannelUri channelUri)
    {
        final String groupTagValue = channelUri.get(GROUP_TAG_PARAM_NAME);
        if (null == groupTagValue)
        {
            groupTag = null;
            return this;
        }
        else
        {
            try
            {
                return groupTag(Long.valueOf(groupTagValue));
            }
            catch (final NumberFormatException ex)
            {
                throw new IllegalArgumentException("'gtag' must be a valid long value", ex);
            }
        }
    }

    /**
     * Get the group tag (gtag) to be sent in SMs (Status Messages).
     *
     * @return receiver tag to be sent in SMs.
     * @see CommonContext#GROUP_TAG_PARAM_NAME
     */
    public Long groupTag()
    {
        return groupTag;
    }

    /**
     * Set the subscription semantics for if a stream should be rejoined after going unavailable.
     *

View on GitHub (pinned to 6d60124e15)