aeron-io/aeron · error · InvalidChannelException

publication-window-length=

Error message

publication-window-length={pubWindow} must not exceed half the term-length={termLength}

What it means

publication-window-length must not exceed half the term-length; a window larger than half a term buffer would let the producer overrun the consumer position into the next term and break flow-control invariants. Aeron rejects such values with InvalidChannelException.

Solutions

Set publication-window-length <= termLength >> 1
Increase term-length so that half of it exceeds the desired window
Remove the publication-window-length param to accept the driver default

Example fix

// before
"aeron:udp?endpoint=...:40456|term-length=1m|publication-window-length=2m"
// after
"aeron:udp?endpoint=...:40456|term-length=4m|publication-window-length=2m"

Defensive patterns

Strategy: validation

Validate before calling

if (publicationWindowLength > (termLength >> 1)) throw new IllegalArgumentException("window must be <= termLength/2");

Try / catch

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

Prevention

Choose window and term-length together from one tuning table
Watch size-unit suffixes (k/m) in URI params
Re-validate URIs after reducing term-length for latency tuning

When it happens

Trigger: A channel URI where publication-window-length > termLength/2 (e.g. publication-window-length=2m with term-length=1m, or a shrunken term-length like term-length=64k with default 1MB window param).

Common situations: Reducing term-length for low-latency small-message channels without adjusting the window; typos in size units (m vs k) in the URI; copying a window value from a driver-level config into a channel URI with smaller terms.

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

Appendix: source

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

        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());
        }
    }

    private void getStreamId(final ChannelUri channelUri, final int streamId)
    {
        final String streamIdParam = channelUri.get(STREAM_ID_PARAM_NAME);
        if (null != streamIdParam)
        {

View on GitHub (pinned to 6d60124e15)