aeron-io/aeron · error · InvalidChannelException

= does not match existing value of : existingChannel=…

Error message

${paramName}=${newLength} does not match existing value of ${existingValue}: existingChannel=${existingChannel} channel=${channel}

What it means

When a second publication or subscription reuses an existing channel endpoint, its SO_SNDBUF/SO_RCVBUF length must either be 0 (OS default) or exactly match the value already in use, because one socket is shared. This InvalidChannelException reports the mismatch between the requested param length and the existing socket buffer size.

Solutions

Use the same socket/term buffer length as the existing channel on that endpoint
Set the length to 0 (OS default) on the new channel if the existing one uses the OS default
Close the existing publications/subscriptions on that endpoint before adding with new lengths
Unify buffer-size settings in one shared configuration

Example fix

// before
aeron.addPublication("aeron:udp?endpoint=localhost:40456|so-sndbuf=128k", 1001); // existing is 64k
// after
aeron.addPublication("aeron:udp?endpoint=localhost:40456|so-sndbuf=64k", 1001);

Defensive patterns

Strategy: validation

Validate before calling

Long sndbuf = uriParamLong(channel, "so-sndbuf", 0L);
Long existing = existingBufferLengthForEndpoint(canonicalChannel);
if (existing != null && sndbuf != 0 && !sndbuf.equals(existing)) {
    throw new IllegalArgumentException("so-sndbuf=" + sndbuf + " conflicts with existing " + existing);
}

Try / catch

try { aeron.addPublication(channel, streamId); } catch (InvalidChannelException e) { if (e.getMessage().contains("does not match existing value of")) { log.error("buffer length mismatch: {}", e.getMessage()); } throw e; }

Prevention

Use identical socket-buffer settings for all channels sharing an endpoint
Prefer leaving buffer params unset (OS default) everywhere
Centralize tuning params in shared configuration
Re-check endpoints when changing sizes; close old publications first

When it happens

Trigger: Adding a publication/subscription on a channel that maps to an existing endpoint but with a different term/socket-buffer length parameter, e.g. "aeron:udp?endpoint=h:p|so-sndbuf=128k" after "...|so-sndbuf=64k" exists; one URI omits the param (0 → OS default) while the other sets it.

Common situations: Tuning one consumer's buffer sizes without realizing the endpoint socket is shared; defaults changed in a config template for some services but not others; copying channel URIs between environments with different buffer settings.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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

Appendix: source

Thrown at aeron-driver/src/main/java/io/aeron/driver/DriverConductor.java:2317

            for (int i = 1; i < PARTITION_COUNT; i++)
            {
                final int expectedTermId = (initialTermId + i) - PARTITION_COUNT;
                initialiseTailWithTermId(logMetaData, i, expectedTermId);
            }
        }
    }

    private static void validateChannelBufferLength(
        final String paramName,
        final int newLength,
        final int existingLength,
        final String channel,
        final String existingChannel)
    {
        if (0 != newLength && newLength != existingLength)
        {
            final Object existingValue = 0 == existingLength ? "OS default" : existingLength;
            throw new InvalidChannelException(
                paramName + "=" + newLength + " does not match existing value of " + existingValue +
                    ": existingChannel=" + existingChannel + " channel=" + channel);
        }
    }

    private static void validateEndpointForPublication(final UdpChannel udpChannel)
    {
        if (!udpChannel.isMultiDestination() && udpChannel.hasExplicitEndpoint() &&
            0 == udpChannel.remoteData().getPort())
        {
            throw new IllegalArgumentException(
                ENDPOINT_PARAM_NAME + " has port=0 for publication: channel=" + udpChannel.originalUriString());
        }
    }

    private static void validateControlForPublication(final UdpChannel udpChannel)
    {
        if (udpChannel.isDynamicControlMode() && !udpChannel.hasExplicitControl())

View on GitHub (pinned to 6d60124e15)