aeron-io/aeron · error · InvalidChannelException

sessionId= has an invalid tag: channel=

Error message

sessionId=<sessionIdStr> has an invalid tag: channel=<channelUri>

What it means

Aeron throws InvalidChannelException when the `session-id` URI parameter is given as a tagged reference (e.g. `session-id=tag:xyz`) but the tag string cannot be parsed into a valid channel tag by ChannelUri.getTag. The tagged form requires the referenced publication's tag, not an arbitrary string.

Solutions

  1. Ensure the value uses valid tag syntax, e.g. session-id=tag:1001
  2. Reference an existing publication's actual tag as assigned by the driver or via an entity tag
  3. Use a plain numeric session-id if you do not need tag-based referencing
  4. Validate the URI with ChannelUri.parse/addSessionId before passing it to Aeron

Example fix

// before
"aeron:udp?endpoint=localhost:40456|session-id=tag:my-session"
// after
"aeron:udp?endpoint=localhost:40456|session-id=tag:1001"
Defensive patterns

Strategy: validation

Validate before calling

String sessionId = uri.get(SEND_CHANNEL_PARAM_NAME);
if (sessionId != null && sessionId.startsWith("tag:")) {
    try { Long.parseLong(sessionId.substring(4)); } catch (NumberFormatException e) {
        throw new IllegalArgumentException("Invalid tag in session-id: " + sessionId, e);
    }
}

Type guard

boolean isValidTaggedSession(String v) {
    return v != null && v.startsWith("tag:") && Long.parseLong(v.substring(4)) > 0;
}

Try / catch

try { publication = aeron.addPublication(uri, streamId); }
catch (InvalidChannelException e) {
    if (e.getMessage().contains("has an invalid tag")) {
        throw new ConfigurationException("Fix session-id tag syntax in " + uri, e);
    } throw e;
}

Prevention

When it happens

Trigger: Adding a publication with `session-id=tag:...` where the value after 'tag:' is malformed (wrong prefix, non-numeric/invalid tag syntax) so ChannelUri.getTag throws a RuntimeException, which is wrapped.

Common situations: Typos or hand-edited channel URIs; using a session id number where a tag reference is expected; building the URI dynamically and interpolating a null or wrong variable; Aeron version differences in tag syntax.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

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

Appendix: source

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

        final ChannelUri channelUri,
        final DriverConductor driverConductor,
        final int streamId,
        final String canonicalForm)
    {
        final String sessionIdStr = channelUri.get(SESSION_ID_PARAM_NAME);
        if (null != sessionIdStr)
        {
            isSessionIdTagged = ChannelUri.isTagged(sessionIdStr);
            if (isSessionIdTagged)
            {
                final long tag;
                try
                {
                    tag = ChannelUri.getTag(sessionIdStr);
                }
                catch (final RuntimeException ex)
                {
                    throw new InvalidChannelException(
                        SESSION_ID_PARAM_NAME + "=" + sessionIdStr + " has an invalid tag: channel=" + channelUri, ex);
                }

                if (channelUri.isIpc())
                {
                    final IpcPublication publication = driverConductor.findIpcPublicationByTag(tag);
                    if (null == publication)
                    {
                        throw new InvalidChannelException(
                            SESSION_ID_PARAM_NAME + "=" + sessionIdStr + " must reference an IPC publication: " +
                            "channel=" + channelUri);
                    }

                    sessionId = publication.sessionId();
                    mtuLength = publication.mtuLength();
                    termLength = publication.termBufferLength();
                }
                else

View on GitHub (pinned to 6d60124e15)