aeron-io/aeron · error · InvalidChannelException

entityTag already in use: existingChannel= channel=

Error message

<entityTag> entityTag already in use: existingChannel=<channel> channel=<channelUri>

What it means

A publication entity tag must be unique among active network publications. If driverConductor.findNetworkPublicationByTag returns an existing publication with the same tag, the driver rejects the new channel, reporting the conflicting channel URI.

Solutions

Use a distinct tag per publication (e.g. derived from session/stream or an id allocator).
Close the existing publication holding the tag before adding a new one with it.
Wait for the old publication to be fully closed if it is shutting down, or check Aeron client errors for the duplicate.
If the channel is intentionally identical, reuse the existing Publication instead of adding a new one.

Example fix

// before
long tag = 1001; // hardcoded, reused everywhere
// after
long tag = TagAllocator.next(); // unique per live publication

Defensive patterns

Strategy: try-catch

Validate before calling

// Track live tags in your application to guarantee uniqueness before calling addPublication
Set<Long> inUseTags = ConcurrentHashMap.newKeySet();
if (!inUseTags.add(tag)) { /* pick another tag */ }

Try / catch

try {
    publication = aeron.addPublication(channel, streamId);
} catch (AeronException e) {
    if (e.getMessage().contains("entityTag already in use")) { /* choose a unique tag or close the old publication */ }
    throw e;
}

Prevention

Allocate tags from a central id allocator per process/host.
Close publications deterministically before reusing tags.
Avoid hardcoded tag literals shared across configs.

When it happens

Trigger: Adding a second network publication whose entity tag matches a currently live publication, e.g. reusing tag=1001 on two channels at once.

Common situations: Reusing hardcoded tag values across services or channels; a previous publication still active (not yet closed) while restarting with the same tag; duplicate config across instances.

Related errors

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

Appendix: source

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

        final long entityTag;
        try
        {
            entityTag = Long.parseLong(tagParam);
        }
        catch (final NumberFormatException ex)
        {
            throw new InvalidChannelException("invalid entity tag, must be a number", ex);
        }

        if (INVALID_TAG == entityTag)
        {
            throw new InvalidChannelException(INVALID_TAG + " tag is reserved: channel=" + channelUri);
        }

        final NetworkPublication networkPublication = driverConductor.findNetworkPublicationByTag(entityTag);
        if (null != networkPublication)
        {
            throw new InvalidChannelException(entityTag + " entityTag already in use: existingChannel=" +
                networkPublication.channel() + " channel=" + channelUri);
        }
        final IpcPublication ipcPublication = driverConductor.findIpcPublicationByTag(entityTag);
        if (null != ipcPublication)
        {
            throw new InvalidChannelException(entityTag + " entityTag already in use: existingChannel=" +
                ipcPublication.channel() + " channel=" + channelUri);
        }

        return entityTag;
    }

    public String toString()
    {
        return "PublicationParams{" +
            "lingerTimeoutNs=" + lingerTimeoutNs +
            ", entityTag=" + entityTag +
            ", termLength=" + termLength +

View on GitHub (pinned to 6d60124e15)