aeron-io/aeron · error · InvalidChannelException

invalid responseCorrelationId, must be a number greater…

Error message

invalid responseCorrelationId, must be a number greater than or equal to -1, or '<PROTOTYPE_CORRELATION_ID>'

What it means

parseResponseCorrelationId parses the `response-correlation-id` URI parameter (for MDS/route-to-response publications) and throws InvalidChannelException on NumberFormatException when the value is not a number >= -1 and not the PROTOTYPE_CORRELATION_ID sentinel.

Solutions

1. Set response-correlation-id to a valid decimal long >= -1, typically a live image/subscription correlation id obtained from the driver
2. Use the PROTOTYPE_CORRELATION_ID sentinel if only declaring a prototype response publication
3. Omit the parameter entirely if response routing is not needed
4. Validate the value with Long.parseLong and a >= -1 check before building the URI

Example fix

// before
"aeron:udp?endpoint=localhost:40456|response-correlation-id=-42"
// after
"aeron:udp?endpoint=localhost:40456|response-correlation-id=123456789"

long v;
try { v = Long.parseLong(value.trim()); }
catch (NumberFormatException e) { throw new IllegalArgumentException("response-correlation-id must be numeric"); }
if (v < -1) throw new IllegalArgumentException("response-correlation-id must be >= -1");

boolean isValidResponseCorrelationId(String v) {
    try { long x = Long.parseLong(v.trim()); return x >= -1; } catch (NumberFormatException e) { return false; }
}

try { publication = aeron.addPublication(uri, streamId); }
catch (InvalidChannelException e) {
    if (e.getMessage().contains("response-correlation-id")) {
        throw new ConfigurationException("response-correlation-id must be a number >= -1 or the prototype sentinel", e);
    } throw e;
}

When it happens

Trigger: Adding a publication whose channel URI contains `response-correlation-id=<value>` where value is non-numeric, empty, or numerically less than -1 (e.g. -5), and it is not the prototype sentinel value.

Common situations: Plugging a subscription's registrationId captured before publication creation; copying a UUID or hex string instead of a decimal long; template placeholders like `${corrId}` left unsubstituted; sign/overflow mistakes.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• destinations must not contain the key
• difference greater than 2^31 - 1: termId=
• invalid control mode
• invalid maxResend= , must be > 0 and <=
• invalid media

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

Appendix: source

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

        if (PROTOTYPE_CORRELATION_ID.equals(idStr))
        {
            return PROTOTYPE_VALUE_CORRELATION_ID;
        }

        try
        {
            final long value = Long.parseLong(idStr);

            if (value < -1)
            {
                throw new NumberFormatException("responseCorrelationId must be positive");
            }

            return value;
        }
        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)

View on GitHub (pinned to 6d60124e15)