aeron-io/aeron · error · InvalidChannelException

sessionId= must reference an IPC publication: channel=

Error message

sessionId=<sessionIdStr> must reference an IPC publication: channel=<channelUri>

What it means

The `session-id` URI parameter referenced a well-formed tag, but on an IPC channel no existing IpcPublication with that tag exists in the driver conductor. Aeron throws InvalidChannelException because tagged session ids must point at an already-created publication to reuse its session id, MTU, and other params.

Solutions

Create the tagged IPC publication before adding the channel that references its tag
Confirm the tag matches the existing IPC publication's tag (check its registration output)
Check for premature close of the referenced publication
If the target is a network publication, use a aeron:udp channel instead of aeron:ipc

Example fix

// before (no IPC publication with tag 42 exists)
aeron.addPublication("aeron:ipc|session-id=tag:42", 1001);
// after
Publication p = aeron.addPublication("aeron:ipc|tags=1001,42", 1001);
Publication q = aeron.addPublication("aeron:ipc|session-id=tag:42", 1001);

Defensive patterns

Strategy: validation

Validate before calling

IpcPublication p = driverConductor.findIpcPublicationByTag(tag);
if (p == null) throw new IllegalStateException("Tagged IPC publication " + tag + " must be created first");

Try / catch

try { publication = aeron.addPublication("aeron:ipc|session-id=tag:" + tag, streamId); }
catch (InvalidChannelException e) {
    if (e.getMessage().contains("must reference an IPC publication")) {
        // create the tagged publication first, then retry
    } throw e;
}

Prevention

Enforce creation order: tagged publication before referencing publications
Track referenced publication lifecycles and close dependents together
Do not reuse network tags on IPC channels

When it happens

Trigger: Adding an IPC publication with `session-id=tag:<t>` where findIpcPublicationByTag returns null — the referenced publication was never created, was closed, or the tag belongs to a network (not IPC) publication.

Common situations: Ordering bugs: subscriber/publication with tag reference added before the tagged publication is created; the source publication was closed; tag typo; referencing a UDP publication's tag from an IPC (aeron:ipc) channel.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

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

Appendix: source

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

            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
                {
                    final NetworkPublication publication = driverConductor.findNetworkPublicationByTag(tag);
                    if (null == publication)
                    {
                        throw new InvalidChannelException(
                            SESSION_ID_PARAM_NAME + "=" + sessionIdStr + " must reference a network publication: " +
                            "channel=" + channelUri);
                    }

View on GitHub (pinned to 6d60124e15)