{"record":{"id":"94df3bddcea6648c","repo":"aeron-io/aeron","slug":"entitytag-entitytag-already-in-use-existingchannel-channel","errorCode":null,"errorMessage":"<entityTag> entityTag already in use: existingChannel=<channel> channel=<channelUri>","messagePattern":"<entityTag> entityTag already in use: existingChannel=<channel> channel=<channelUri>","errorType":"exception","errorClass":"InvalidChannelException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/PublicationParams.java","lineNumber":616,"sourceCode":"        final long entityTag;\n        try\n        {\n            entityTag = Long.parseLong(tagParam);\n        }\n        catch (final NumberFormatException ex)\n        {\n            throw new InvalidChannelException(\"invalid entity tag, must be a number\", ex);\n        }\n\n        if (INVALID_TAG == entityTag)\n        {\n            throw new InvalidChannelException(INVALID_TAG + \" tag is reserved: channel=\" + channelUri);\n        }\n\n        final NetworkPublication networkPublication = driverConductor.findNetworkPublicationByTag(entityTag);\n        if (null != networkPublication)\n        {\n            throw new InvalidChannelException(entityTag + \" entityTag already in use: existingChannel=\" +\n                networkPublication.channel() + \" channel=\" + channelUri);\n        }\n        final IpcPublication ipcPublication = driverConductor.findIpcPublicationByTag(entityTag);\n        if (null != ipcPublication)\n        {\n            throw new InvalidChannelException(entityTag + \" entityTag already in use: existingChannel=\" +\n                ipcPublication.channel() + \" channel=\" + channelUri);\n        }\n\n        return entityTag;\n    }\n\n    public String toString()\n    {\n        return \"PublicationParams{\" +\n            \"lingerTimeoutNs=\" + lingerTimeoutNs +\n            \", entityTag=\" + entityTag +\n            \", termLength=\" + termLength +","sourceCodeStart":598,"sourceCodeEnd":634,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/PublicationParams.java#L598-L634","documentation":"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.","triggerScenarios":"Adding a second network publication whose entity tag matches a currently live publication, e.g. reusing tag=1001 on two channels at once.","commonSituations":"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.","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."],"exampleFix":"// before\nlong tag = 1001; // hardcoded, reused everywhere\n// after\nlong tag = TagAllocator.next(); // unique per live publication","handlingStrategy":"try-catch","validationCode":"// Track live tags in your application to guarantee uniqueness before calling addPublication\nSet<Long> inUseTags = ConcurrentHashMap.newKeySet();\nif (!inUseTags.add(tag)) { /* pick another tag */ }","typeGuard":null,"tryCatchPattern":"try {\n    publication = aeron.addPublication(channel, streamId);\n} catch (AeronException e) {\n    if (e.getMessage().contains(\"entityTag already in use\")) { /* choose a unique tag or close the old publication */ }\n    throw e;\n}","preventionTips":["Allocate tags from a central id allocator per process/host.","Close publications deterministically before reusing tags.","Avoid hardcoded tag literals shared across configs."],"tags":["aeron","channel-uri","duplicate-resource","tags"],"backgroundTag":"address-already-in-use","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}