aeron-io/aeron · error · InvalidChannelException

publication-window-length=

Error message

publication-window-length={pubWindow} cannot be less than the mtu-length={mtuLength}

What it means

The publication-window-length URI parameter controls how far ahead a publication may send; it must be at least the MTU length or no single maximum-sized message could ever fit in the window. Values below mtu-length are rejected with InvalidChannelException.

Solutions

Raise publication-window-length to >= mtu-length
Lower mtu-length to be <= the desired window
Remove publication-window-length and use the context default

Example fix

// before
"aeron:udp?endpoint=...:40456|mtu-length=16384|publication-window-length=8k"
// after
"aeron:udp?endpoint=...:40456|mtu-length=16384|publication-window-length=16k"

Defensive patterns

Strategy: validation

Validate before calling

if (publicationWindowLength < mtuLength) throw new IllegalArgumentException("window must be >= mtu-length");

Try / catch

try { pub = aeron.addPublication(uri, streamId); } catch (InvalidChannelException e) { log.error("window vs mtu conflict: {}", e.getMessage()); }

Prevention

Validate window >= mtu whenever changing mtu-length
Keep window/mtu pairs in one config block
Re-check channel URIs after tuning MTU for jumbo frames

When it happens

Trigger: A channel URI with publication-window-length smaller than the effective mtu-length (e.g. publication-window-length=1k with mtu-length=8192, or a raised mtu-length that overtakes a fixed window).

Common situations: Tuning MTU up (e.g. for jumbo frames) while keeping a small window from an older config; copy-pasted URI params tuned for a different network; setting window in KB but MTU left at default after edits.

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/f056548486fdb4cb. Report an issue: GitHub.

Appendix: source

Thrown at aeron-driver/src/main/java/io/aeron/driver/PublicationParams.java:177

            params.termId = params.initialTermId;
            params.termOffset = 0;
        }

        params.isResponse = CONTROL_MODE_RESPONSE.equals(channelUri.get(MDC_CONTROL_MODE_PARAM_NAME));
        params.responseCorrelationId = parseResponseCorrelationId(channelUri);

        return params;
    }

    private void getPublicationWindowLength(final ChannelUri channelUri, final MediaDriver.Context ctx)
    {
        final String pubWindowParam = channelUri.get(PUBLICATION_WINDOW_LENGTH_PARAM_NAME);
        if (null != pubWindowParam)
        {
            final long pubWindow = SystemUtil.parseSize(PUBLICATION_WINDOW_LENGTH_PARAM_NAME, pubWindowParam);
            if (pubWindow < mtuLength)
            {
                throw new InvalidChannelException(
                    PUBLICATION_WINDOW_LENGTH_PARAM_NAME + "=" + pubWindow + " cannot be less than the " +
                    MTU_LENGTH_PARAM_NAME + "=" + mtuLength);
            }

            if (pubWindow > (termLength >> 1))
            {
                throw new InvalidChannelException(
                    PUBLICATION_WINDOW_LENGTH_PARAM_NAME + "=" + pubWindow + " must not exceed half the " +
                    TERM_LENGTH_PARAM_NAME + "=" + termLength);
            }
            publicationWindowLength = (int)pubWindow;
        }
        else
        {
            publicationWindowLength = Configuration.producerWindowLength(
                termLength,
                channelUri.isIpc() ? ctx.ipcPublicationTermWindowLength() : ctx.publicationTermWindowLength());
        }

View on GitHub (pinned to 6d60124e15)