{"record":{"id":"af0a949c33358a56","repo":"aeron-io/aeron","slug":"invalid-entity-tag-must-be-a-number","errorCode":null,"errorMessage":"invalid entity tag, must be a number","messagePattern":"invalid entity tag, must be a number","errorType":"exception","errorClass":"InvalidChannelException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/PublicationParams.java","lineNumber":605,"sourceCode":"        }\n        catch (final NumberFormatException ex)\n        {\n            throw new InvalidChannelException(\"invalid \" + RESPONSE_CORRELATION_ID_PARAM_NAME +\n                \", must be a number greater than or equal to -1, or '\" + PROTOTYPE_CORRELATION_ID + \"'\", ex);\n        }\n    }\n\n    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        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);","sourceCodeStart":587,"sourceCodeEnd":623,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/PublicationParams.java#L587-L623","documentation":"Aeron's publication entity tag URI parameter must be a signed 64-bit number. During channel URI parsing in the driver, Long.parseLong fails on the supplied value and InvalidChannelException is thrown. The channel is rejected before a publication is created.","triggerScenarios":"Adding a publication whose channel URI contains an entity-tag (or tag) param with a non-numeric value, e.g. aeron:udp?endpoint=...|tag=abc123 or an empty/whitespace value.","commonSituations":"Hand-edited channel strings, config templates with unresolved placeholders (tag=${id}), copying a tag including letters or units, or concatenating strings into URIs programmatically.","solutions":["Set the tag param to a plain 64-bit integer literal, e.g. tag=1001.","Validate/parse the value with Long.parseLong before building the channel URI.","If the tag comes from config/env, resolve placeholders and strip whitespace before interpolation."],"exampleFix":"// before\nString channel = \"aeron:udp?endpoint=localhost:40456|tag=\" + config.getTag();\n// after\nlong tag = Long.parseLong(config.getTag().trim());\nString channel = \"aeron:udp?endpoint=localhost:40456|tag=\" + tag;","handlingStrategy":"validation","validationCode":"boolean isValidEntityTag(String tag) {\n    try { Long.parseLong(tag.trim()); return true; } catch (NumberFormatException e) { return false; }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Build channel URIs from typed values (long) not raw strings.","Validate numeric params with Long.parseLong before URI assembly.","Resolve config placeholders and trim values before interpolation."],"tags":["aeron","channel-uri","config","parsing"],"backgroundTag":"invalid-argument-format","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"}