aeron-io/aeron · error · InvalidChannelException

invalid entity tag, must be a number

Error message

invalid entity tag, must be a number

What it means

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.

Solutions

1. Set the tag param to a plain 64-bit integer literal, e.g. tag=1001.
2. Validate/parse the value with Long.parseLong before building the channel URI.
3. If the tag comes from config/env, resolve placeholders and strip whitespace before interpolation.

Example fix

// before
String channel = "aeron:udp?endpoint=localhost:40456|tag=" + config.getTag();
// after
long tag = Long.parseLong(config.getTag().trim());
String channel = "aeron:udp?endpoint=localhost:40456|tag=" + tag;

boolean isValidEntityTag(String tag) {
    try { Long.parseLong(tag.trim()); return true; } catch (NumberFormatException e) { return false; }
}

When it happens

Trigger: 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.

Common situations: Hand-edited channel strings, config templates with unresolved placeholders (tag=${id}), copying a tag including letters or units, or concatenating strings into URIs programmatically.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• 'ttl' must be a value integer
• >
• value exceeds maximum permitted: value=
• must be a number
• invalid member value

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

Appendix: source

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

        }
        catch (final NumberFormatException ex)
        {
            throw new InvalidChannelException("invalid " + RESPONSE_CORRELATION_ID_PARAM_NAME +
                ", must be a number greater than or equal to -1, or '" + PROTOTYPE_CORRELATION_ID + "'", ex);
        }
    }

    private static long parseEntityTag(
        final String tagParam, final DriverConductor driverConductor, final ChannelUri channelUri)
    {
        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);

View on GitHub (pinned to 6d60124e15)