aeron-io/aeron · error · NumberFormatException

responseCorrelationId must be positive

Error message

responseCorrelationId must be positive

What it means

Internal NumberFormatException thrown while validating the response_correlation_id channel URI parameter. When the value is not the prototype keyword and parses as a long, it must be >= -1 (with -1 typically meaning 'no response'); any smaller parsed value raises this NumberFormatException, which the builder then converts into a richer IllegalArgumentException (error 248).

Solutions

  1. Use the actual positive correlationId returned from Aeron's asyncClient.addPublication/addCounter futures.
  2. Use -1 (or the prototype keyword) for the special 'no response' case instead of an arbitrary negative sentinel.
  3. Treat correlation IDs as unsigned 64-bit (Long.parseUnsignedLong) if they originate from unsigned representations.

Example fix

// before
builder.responseCorrelationId(String.valueOf(-99999));
// after
builder.responseCorrelationId(Long.toString(correlationId)); // correlationId >= -1, from Aeron client future
Defensive patterns

Strategy: validation

Validate before calling

void checkResponseCorrelationId(String value) {
    if (value == null) return;
    if ("PROTOTYPE".equals(value)) return;
    long id = Long.parseLong(value);
    if (id < -1) throw new IllegalArgumentException("responseCorrelationId must be >= -1: " + value);
}

Type guard

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

Try / catch

try {
    builder.responseCorrelationId(idString);
} catch (IllegalArgumentException e) {
    log.error("Bad response_correlation_id '{}'", idString, e);
    throw new ConfigException("Check response_correlation_id: must be a number >= -1 or 'PROTOTYPE'", e);
}

Prevention

When it happens

Trigger: Parsing a channel URI containing response_correlation_id=<number less than -1> (e.g. -5000) via ChannelUriStringBuilder, where the value is not the PROTOTYPE_CORRELATION_ID keyword.

Common situations: Correlation IDs wrapped/mangled from unsigned 64-bit values into negative longs; placeholder values like -99999 left in templates; bit-truncated IDs from another system.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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

Appendix: source

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

    }

    /**
     * Set the correlation id from the image received on the response "server's" subscription to be used by a response
     * publication.
     *
     * @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.
     *

View on GitHub (pinned to 6d60124e15)