aeron-io/aeron · error · InvalidChannelException

stream-id= does not match provided streamId=

Error message

stream-id={configuredStreamId} does not match provided streamId={streamId}

What it means

If a stream-id URI parameter is present it must match the streamId passed to the API call (e.g. Aeron.addPublication(channel, streamId)). A mismatch means the URI and the programmatic argument disagree, so Aeron throws InvalidChannelException instead of guessing which one is intended.

Solutions

1. Make the streamId argument match the stream-id URI param (or vice versa)
2. Strip the stream-id param from the channel URI and pass streamId only programmatically
3. Parse the URI with ChannelUri and use its stream-id value as the single source of truth

Example fix

// before
aeron.addPublication("aeron:udp?endpoint=...:40456|stream-id=1001", 1002);
// after
aeron.addPublication("aeron:udp?endpoint=...:40456", 1001);

ChannelUri c = ChannelUri.parse(uri); String p = c.get("stream-id"); if (p != null && Integer.parseInt(p) != streamId) throw new IllegalArgumentException("stream-id mismatch");

try { pub = aeron.addPublication(uri, streamId); } catch (InvalidChannelException e) { log.error("stream-id mismatch: {}", e.getMessage()); }

When it happens

Trigger: Calling addPublication/addExclusivePublication with a streamId different from the stream-id= param embedded in the channel URI string.

Common situations: Building URIs from config that already include stream-id while passing a separate (stale) streamId variable; changing stream IDs in one place (config) but not the other (code); template URIs with a hardcoded stream-id reused across topics.

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

• difference greater than 2^31 - 1: initial-term-id=
• invalid prefix
• params must be used as a complete set: initial-term-id…
• term-offset= must be a multiple of FRAME_ALIGNMENT: channel=
• term-offset= out of range: channel=

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

Appendix: source

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

            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)
        {
            final int configuredStreamId = parseInt(streamIdParam, STREAM_ID_PARAM_NAME);
            if (streamId != configuredStreamId)
            {
                throw new InvalidChannelException(
                    STREAM_ID_PARAM_NAME + "=" + configuredStreamId + " does not match provided streamId=" + streamId);
            }
        }
        this.streamId = streamId;
    }

    private void getEntityTag(final ChannelUri channelUri, final DriverConductor driverConductor)
    {
        final String tagParam = channelUri.entityTag();
        if (null != tagParam)
        {
            this.entityTag = parseEntityTag(tagParam, driverConductor, channelUri);
        }
    }

    private void getTermBufferLength(final ChannelUri channelUri)
    {
        final String termLengthParam = channelUri.get(TERM_LENGTH_PARAM_NAME);

View on GitHub (pinned to 6d60124e15)