{"record":{"id":"9fc51c3f69489ab4","repo":"aeron-io/aeron","slug":"invalid-tag-tag-is-reserved-channel-channeluri","errorCode":null,"errorMessage":"<INVALID_TAG> tag is reserved: channel=<channelUri>","messagePattern":"<INVALID_TAG> tag is reserved: channel=<channelUri>","errorType":"exception","errorClass":"InvalidChannelException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/PublicationParams.java","lineNumber":610,"sourceCode":"private static long parseEntityTag(\n    final String tagParam, final DriverConductor driverConductor, final ChannelUri channelUri)\n{\n    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\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}","sourceCodeStart":592,"sourceCodeEnd":628,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/PublicationParams.java#L592-L628","documentation":"Sentinel validation in the driver's entity tag parsing for tagged publications/subscriptions. The tag= URI parameter identifies an entity by long value, and Aeron reserves the special value INVALID_TAG (-1) as the 'no tag' sentinel, so it cannot be used as an actual entity tag. The exception fires when the parsed entityTag equals INVALID_TAG, rejecting a channel URI that explicitly assigns the reserved sentinel value.","triggerScenarios":"Adding a publication with |tag=-1 (or any value equal to Aeron.NULL_VALUE / INVALID_TAG) in the channel URI.","commonSituations":"Using -1 as a default/placeholder tag value in configuration; code that forwards Aeron.NULL_VALUE into the URI; misconfigured tag generators starting at -1.","solutions":["Choose any tag value other than -1, e.g. a positive session-like id.","If the tag is optional, omit the tag param from the URI instead of using -1.","Add a pre-check: if (tag == Aeron.NULL_VALUE) omit or replace the tag before building the URI."],"exampleFix":"// before\nString channel = \"aeron:udp?endpoint=localhost:40456|tag=\" + tag; // tag == -1\n// after\nString channel = tag != Aeron.NULL_VALUE\n    ? \"aeron:udp?endpoint=localhost:40456|tag=\" + tag\n    : \"aeron:udp?endpoint=localhost:40456\";","handlingStrategy":"validation","validationCode":"if (tag == Aeron.NULL_VALUE) { throw new IllegalArgumentException(\"tag=-1 is reserved; omit tag or use another value\"); }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never default tag values to -1; omit the param instead.","Centralize URI building so reserved-value checks live in one place."],"tags":["aeron","channel-uri","reserved-value","config"],"backgroundTag":"invalid-argument-value","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}