{"record":{"id":"f39ff5cf3c65689f","repo":"aeron-io/aeron","slug":"responsecorrelationid-must-be-a-number-greater-than-or-equal","errorCode":null,"errorMessage":"responseCorrelationId must be a number greater than or equal to -1, or the value '${PROTOTYPE_CORRELATION_ID}' found: ${responseCorrelationId}","messagePattern":"responseCorrelationId must be a number greater than or equal to -1, or the value '(.+?)' found: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/ChannelUriStringBuilder.java","lineNumber":2051,"sourceCode":"     *\n     * @param responseCorrelationId correlation id of an image from the response \"server's\" subscription.\n     * @return this for a fluent API.\n     * @see CommonContext#RESPONSE_CORRELATION_ID_PARAM_NAME\n     */\n    public ChannelUriStringBuilder responseCorrelationId(final String responseCorrelationId)\n    {\n        if (null != responseCorrelationId && !PROTOTYPE_CORRELATION_ID.equals(responseCorrelationId))\n        {\n            try\n            {\n                if (Long.parseLong(responseCorrelationId) < -1)\n                {\n                    throw new NumberFormatException(\"responseCorrelationId must be positive\");\n                }\n            }\n            catch (final NumberFormatException ex)\n            {\n                throw new IllegalArgumentException(\n                    \"responseCorrelationId must be a number greater than or equal to -1, or the value '\" +\n                        PROTOTYPE_CORRELATION_ID + \"' found: \" + responseCorrelationId);\n            }\n        }\n\n        this.responseCorrelationId = responseCorrelationId;\n        return this;\n    }\n\n    /**\n     * Set the correlation id from the image received on the response \"server's\" subscription to be used by a response\n     * publication extracted from the channelUri.\n     *\n     * @param channelUri the existing URI to extract the responseCorrelationId from.\n     * @return this for a fluent API.\n     * @see CommonContext#RESPONSE_CORRELATION_ID_PARAM_NAME\n     */\n    public ChannelUriStringBuilder responseCorrelationId(final ChannelUri channelUri)","sourceCodeStart":2033,"sourceCodeEnd":2069,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/ChannelUriStringBuilder.java#L2033-L2069","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pass the numeric correlation ID string obtained from the Aeron client API (value >= -1).","Use the exact PROTOTYPE_CORRELATION_ID keyword ('PROTOTYPE') for prototype response channels.","If the ID came from an unsigned 64-bit source, convert it with Long.toUnsignedString before embedding it in the URI."],"exampleFix":"// before\nbuilder.responseCorrelationId(\"abc\");\n// after\nbuilder.responseCorrelationId(Long.toUnsignedString(correlationId)); // or \"PROTOTYPE\"","handlingStrategy":"validation","validationCode":"void checkResponseCorrelationId(String value) {\n    if (value == null) return;\n    if (\"PROTOTYPE\".equals(value)) return;\n    if (!value.matches(\"-?\\\\d+\")) {\n        throw new IllegalArgumentException(\"response_correlation_id must be numeric, >= -1, or 'PROTOTYPE': \" + value);\n    }\n    if (Long.parseLong(value) < -1) {\n        throw new IllegalArgumentException(\"response_correlation_id must be >= -1: \" + value);\n    }\n}","typeGuard":"boolean isValidResponseCorrelationId(String value) {\n    if (value == null || \"PROTOTYPE\".equals(value)) return true;\n    try {\n        return Long.parseLong(value) >= -1;\n    } catch (NumberFormatException e) {\n        return false;\n    }\n}","tryCatchPattern":"try {\n    builder.responseCorrelationId(value);\n} catch (IllegalArgumentException e) {\n    log.error(\"response_correlation_id '{}' invalid: must be number >= -1 or PROTOTYPE\", value, e);\n    throw e;\n}","preventionTips":["Never embed placeholder text in response_correlation_id; generate real IDs from the client API.","Use the exact prototype keyword spelled as PROTOTYPE_CORRELATION_ID defines it.","Convert unsigned 64-bit IDs with Long.toUnsignedString before URI assembly."],"tags":["aeron","channel-uri","correlation-id","format"],"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-16T04:17:20.429Z"}