aeron-io/aeron · error · IllegalArgumentException

responseCorrelationId must be a number greater than or…

Error message

responseCorrelationId must be a number greater than or equal to -1, or the value '${PROTOTYPE_CORRELATION_ID}' found: ${responseCorrelationId}

What it means

Thrown when the response_correlation_id channel URI parameter is neither a valid number >= -1 nor the special prototype keyword (PROTOTYPE_CORRELATION_ID). It wraps the NumberFormatException raised during validation (including the 'must be positive' check) into an IllegalArgumentException describing all accepted forms.

Solutions

1. Pass the numeric correlation ID string obtained from the Aeron client API (value >= -1).
2. Use the exact PROTOTYPE_CORRELATION_ID keyword ('PROTOTYPE') for prototype response channels.
3. If the ID came from an unsigned 64-bit source, convert it with Long.toUnsignedString before embedding it in the URI.

Example fix

// before
builder.responseCorrelationId("abc");
// after
builder.responseCorrelationId(Long.toUnsignedString(correlationId)); // or "PROTOTYPE"

void checkResponseCorrelationId(String value) {
    if (value == null) return;
    if ("PROTOTYPE".equals(value)) return;
    if (!value.matches("-?\\d+")) {
        throw new IllegalArgumentException("response_correlation_id must be numeric, >= -1, or 'PROTOTYPE': " + value);
    }
    if (Long.parseLong(value) < -1) {
        throw new IllegalArgumentException("response_correlation_id must be >= -1: " + value);
    }
}

boolean isValidResponseCorrelationId(String value) {
    if (value == null || "PROTOTYPE".equals(value)) return true;
    try {
        return Long.parseLong(value) >= -1;
    } catch (NumberFormatException e) {
        return false;
    }
}

try {
    builder.responseCorrelationId(value);
} catch (IllegalArgumentException e) {
    log.error("response_correlation_id '{}' invalid: must be number >= -1 or PROTOTYPE", value, e);
    throw e;
}

When it happens

Trigger: Building/parsing a channel URI with response_correlation_id set to a non-numeric string (e.g. 'abc'), a number < -1, or a misspelled prototype keyword via ChannelUriStringBuilder.

Common situations: Response channels for routed/resp publications configured with placeholder text; misspelled prototype keyword; unsigned-64-bit correlation IDs overflowing into negative numbers or non-numeric strings.

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

• Aeron URIs must start with 'aeron:', found
• mediaReceiveTimestampOffset must be a number or the value
• channelReceiveTimestampOffset must be a number or the value
• channelSendTimestampOffset must be a number or the value
• responseCorrelationId must be positive

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

Appendix: source

Thrown at aeron-client/src/main/java/io/aeron/ChannelUriStringBuilder.java:2051

     *
     * @param responseCorrelationId correlation id of an image from the response "server's" subscription.
     * @return this for a fluent API.
     * @see CommonContext#RESPONSE_CORRELATION_ID_PARAM_NAME
     */
    public ChannelUriStringBuilder responseCorrelationId(final String responseCorrelationId)
    {
        if (null != responseCorrelationId && !PROTOTYPE_CORRELATION_ID.equals(responseCorrelationId))
        {
            try
            {
                if (Long.parseLong(responseCorrelationId) < -1)
                {
                    throw new NumberFormatException("responseCorrelationId must be positive");
                }
            }
            catch (final NumberFormatException ex)
            {
                throw new IllegalArgumentException(
                    "responseCorrelationId must be a number greater than or equal to -1, or the value '" +
                        PROTOTYPE_CORRELATION_ID + "' found: " + responseCorrelationId);
            }
        }

        this.responseCorrelationId = responseCorrelationId;
        return this;
    }

    /**
     * Set the correlation id from the image received on the response "server's" subscription to be used by a response
     * publication extracted from the channelUri.
     *
     * @param channelUri the existing URI to extract the responseCorrelationId from.
     * @return this for a fluent API.
     * @see CommonContext#RESPONSE_CORRELATION_ID_PARAM_NAME
     */
    public ChannelUriStringBuilder responseCorrelationId(final ChannelUri channelUri)

View on GitHub (pinned to 6d60124e15)