aeron-io/aeron · error · IllegalArgumentException

bindAddressAndPort value too long:

Error message

bindAddressAndPort value too long: 

What it means

LocalSocketAddressStatus.updateBindAddress throws IllegalArgumentException when the bindAddressAndPort string exceeds MAX_IPV6_LENGTH, because the value is written into a fixed-size region of the counter's key/metadata buffer and cannot fit. This is a hard capacity limit of the counter key layout, not a network error.

Solutions

1. Shorten the bind address representation before calling (drop scope id, or use canonical IPv6 form)
2. Verify MAX_IPV6_LENGTH and ensure your formatter never exceeds it
3. Catch IllegalArgumentException and log instead of writing when the address string is abnormally long

Example fix

// before
LocalSocketAddressStatus.updateBindAddress(counter, bindAddressAndPort, metadataBuffer);
// after
if (bindAddressAndPort.length() <= MAX_IPV6_LENGTH)
{
    LocalSocketAddressStatus.updateBindAddress(counter, bindAddressAndPort, metadataBuffer);
}

if (bindAddressAndPort != null && bindAddressAndPort.length() > MAX_IPV6_LENGTH) { /* truncate/canonicalize before update */ }

null

try { LocalSocketAddressStatus.updateBindAddress(counter, addr, buf); }
catch (IllegalArgumentException e) { log.warn("bind address too long", e); }

When it happens

Trigger: Calling updateBindAddress with a string whose length() > MAX_IPV6_LENGTH, e.g. an IPv6 address with scope identifier plus port producing a very long literal.

Common situations: IPv6 literals with long interface scope IDs (e.g. 'fe80::1%enp0s31f6:port') formatted into bind address strings; custom channel configurations emitting unusually long bind addresses.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• counter id is negative
• counter id is not allocated, state
• counter id out of range: 0 - maxCounterId=
• Counter not allocated: id=
• EINVAL

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

Appendix: source

Thrown at aeron-client/src/main/java/io/aeron/status/LocalSocketAddressStatus.java:114

        countersManager.setCounterRegistrationId(counter.id(), registrationId);

        return counter;
    }

    /**
     * Update the key metadata and label to contain the bound socket address once the transport is active.
     *
     * @param counter                representing the local socket address of the transport.
     * @param bindAddressAndPort     in string representation.
     * @param countersMetadataBuffer to be updated for the bound address.
     */
    public static void updateBindAddress(
        final AtomicCounter counter, final String bindAddressAndPort, final UnsafeBuffer countersMetadataBuffer)
    {
        if (bindAddressAndPort.length() > MAX_IPV6_LENGTH)
        {
            throw new IllegalArgumentException(
                "bindAddressAndPort value too long: " + bindAddressAndPort.length() + " max: " + MAX_IPV6_LENGTH);
        }

        final int keyIndex = CountersReader.metaDataOffset(counter.id()) + CountersReader.KEY_OFFSET;
        final int addressStringIndex = keyIndex + LOCAL_SOCKET_ADDRESS_STRING_OFFSET;
        final int length = countersMetadataBuffer.putStringWithoutLengthAscii(addressStringIndex, bindAddressAndPort);
        final int addressLengthIndex = keyIndex + LOCAL_SOCKET_ADDRESS_LENGTH_OFFSET;
        countersMetadataBuffer.putInt(addressLengthIndex, length);

        counter.appendToLabel(bindAddressAndPort);
    }

    /**
     * Find the list of currently bound local sockets.
     *
     * @param countersReader  for the connected driver.
     * @param channelStatus   value for the channel which aggregates the transports.
     * @param channelStatusId identity of the counter for the channel which aggregates the transports.

View on GitHub (pinned to 6d60124e15)