{"record":{"id":"3780aeb63ce2d57f","repo":"aeron-io/aeron","slug":"sessionid-sessionidstr-has-an-invalid-tag-channel-channeluri","errorCode":null,"errorMessage":"sessionId=<sessionIdStr> has an invalid tag: channel=<channelUri>","messagePattern":"sessionId=<sessionIdStr> has an invalid tag: channel=<channelUri>","errorType":"exception","errorClass":"InvalidChannelException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/PublicationParams.java","lineNumber":431,"sourceCode":"        final ChannelUri channelUri,\n        final DriverConductor driverConductor,\n        final int streamId,\n        final String canonicalForm)\n    {\n        final String sessionIdStr = channelUri.get(SESSION_ID_PARAM_NAME);\n        if (null != sessionIdStr)\n        {\n            isSessionIdTagged = ChannelUri.isTagged(sessionIdStr);\n            if (isSessionIdTagged)\n            {\n                final long tag;\n                try\n                {\n                    tag = ChannelUri.getTag(sessionIdStr);\n                }\n                catch (final RuntimeException ex)\n                {\n                    throw new InvalidChannelException(\n                        SESSION_ID_PARAM_NAME + \"=\" + sessionIdStr + \" has an invalid tag: channel=\" + channelUri, ex);\n                }\n\n                if (channelUri.isIpc())\n                {\n                    final IpcPublication publication = driverConductor.findIpcPublicationByTag(tag);\n                    if (null == publication)\n                    {\n                        throw new InvalidChannelException(\n                            SESSION_ID_PARAM_NAME + \"=\" + sessionIdStr + \" must reference an IPC publication: \" +\n                            \"channel=\" + channelUri);\n                    }\n\n                    sessionId = publication.sessionId();\n                    mtuLength = publication.mtuLength();\n                    termLength = publication.termBufferLength();\n                }\n                else","sourceCodeStart":413,"sourceCodeEnd":449,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/PublicationParams.java#L413-L449","documentation":"Aeron throws InvalidChannelException when the `session-id` URI parameter is given as a tagged reference (e.g. `session-id=tag:xyz`) but the tag string cannot be parsed into a valid channel tag by ChannelUri.getTag. The tagged form requires the referenced publication's tag, not an arbitrary string.","triggerScenarios":"Adding a publication with `session-id=tag:...` where the value after 'tag:' is malformed (wrong prefix, non-numeric/invalid tag syntax) so ChannelUri.getTag throws a RuntimeException, which is wrapped.","commonSituations":"Typos or hand-edited channel URIs; using a session id number where a tag reference is expected; building the URI dynamically and interpolating a null or wrong variable; Aeron version differences in tag syntax.","solutions":["Ensure the value uses valid tag syntax, e.g. session-id=tag:1001","Reference an existing publication's actual tag as assigned by the driver or via an entity tag","Use a plain numeric session-id if you do not need tag-based referencing","Validate the URI with ChannelUri.parse/addSessionId before passing it to Aeron"],"exampleFix":"// before\n\"aeron:udp?endpoint=localhost:40456|session-id=tag:my-session\"\n// after\n\"aeron:udp?endpoint=localhost:40456|session-id=tag:1001\"","handlingStrategy":"validation","validationCode":"String sessionId = uri.get(SEND_CHANNEL_PARAM_NAME);\nif (sessionId != null && sessionId.startsWith(\"tag:\")) {\n    try { Long.parseLong(sessionId.substring(4)); } catch (NumberFormatException e) {\n        throw new IllegalArgumentException(\"Invalid tag in session-id: \" + sessionId, e);\n    }\n}","typeGuard":"boolean isValidTaggedSession(String v) {\n    return v != null && v.startsWith(\"tag:\") && Long.parseLong(v.substring(4)) > 0;\n}","tryCatchPattern":"try { publication = aeron.addPublication(uri, streamId); }\ncatch (InvalidChannelException e) {\n    if (e.getMessage().contains(\"has an invalid tag\")) {\n        throw new ConfigurationException(\"Fix session-id tag syntax in \" + uri, e);\n    } throw e;\n}","preventionTips":["Construct tagged session ids via ChannelUri.getTag-compatible formatting only","Use entity tags returned by the driver instead of hand-written tags","Unit-test URI builders with representative tag values"],"tags":["aeron","channel-uri","tag","session-id"],"backgroundTag":"invalid-identifier-format","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"}