aeron-io/aeron · error · InvalidChannelException

sessionId= must reference a network publication: channel=

Error message

sessionId=<sessionIdStr> must reference a network publication: channel=<channelUri>

What it means

Same as the IPC case but for network channels: the `session-id=tag:<t>` parameter references a tag for which findNetworkPublicationByTag finds no NetworkPublication, so Aeron throws InvalidChannelException. Tagged session ids must resolve to an existing network publication on the driver.

Solutions

1. Create the tagged network publication first, then the referencing one
2. Verify the tag belongs to a network publication, not an IPC one
3. Confirm the referenced publication is still open at add time
4. Use a fixed numeric session-id instead of tag referencing if no shared publication is intended

Example fix

// before (tag 42 is an IPC publication tag)
aeron.addPublication("aeron:udp?endpoint=localhost:40456|session-id=tag:42", 1001);
// after
Publication p = aeron.addPublication("aeron:udp?endpoint=localhost:40456|tags=1001,42", 1001);
Publication q = aeron.addPublication("aeron:udp?endpoint=localhost:40456|session-id=tag:42", 1001);

NetworkPublication p = driverConductor.findNetworkPublicationByTag(tag);
if (p == null) throw new IllegalStateException("Tagged network publication " + tag + " must be created first");

try { publication = aeron.addPublication("aeron:udp?...|session-id=tag:" + tag, streamId); }
catch (InvalidChannelException e) {
    if (e.getMessage().contains("must reference a network publication")) {
        // create or recreate the tagged publication, then retry once
    } throw e;
}

When it happens

Trigger: Adding a UDP publication with `session-id=tag:<t>` where no NetworkPublication with that tag exists — reference created too early, tag belongs to an IPC publication, or the source publication was closed.

Common situations: Tag lookup across wrong transport (IPC vs UDP); publication closed by unsubscription/race; mistyped tag value; expecting tags to persist after driver restart (they do not).

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

• sessionId= has an invalid tag: channel=
• sessionId= must reference an IPC publication: channel=
• could not resolve control address:
• could not resolve endpoint address:
• either 'endpoint' or 'control' must be specified for UDP.

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

Appendix: source

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

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

                    sessionId = publication.sessionId();
                    mtuLength = publication.mtuLength();
                    termLength = publication.termBufferLength();
                }
            }
            else
            {
                sessionId = parseInt(sessionIdStr, SESSION_ID_PARAM_NAME);
            }
        }
        else
        {
            sessionId = driverConductor.nextAvailableSessionId(streamId, canonicalForm);
        }

View on GitHub (pinned to 6d60124e15)