{"record":{"id":"0c49fcf3d4127243","repo":"aeron-io/aeron","slug":"responsecorrelationid-must-be-positive","errorCode":null,"errorMessage":"responseCorrelationId must be positive","messagePattern":"responseCorrelationId must be positive","errorType":"validation","errorClass":"NumberFormatException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/ChannelUriStringBuilder.java","lineNumber":2046,"sourceCode":"    }\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.\n     *\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     *","sourceCodeStart":2028,"sourceCodeEnd":2064,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/ChannelUriStringBuilder.java#L2028-L2064","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use the actual positive correlationId returned from Aeron's asyncClient.addPublication/addCounter futures.","Use -1 (or the prototype keyword) for the special 'no response' case instead of an arbitrary negative sentinel.","Treat correlation IDs as unsigned 64-bit (Long.parseUnsignedLong) if they originate from unsigned representations."],"exampleFix":"// before\nbuilder.responseCorrelationId(String.valueOf(-99999));\n// after\nbuilder.responseCorrelationId(Long.toString(correlationId)); // correlationId >= -1, from Aeron client future","handlingStrategy":"validation","validationCode":"void checkResponseCorrelationId(String value) {\n    if (value == null) return;\n    if (\"PROTOTYPE\".equals(value)) return;\n    long id = Long.parseLong(value);\n    if (id < -1) throw new IllegalArgumentException(\"responseCorrelationId must be >= -1: \" + value);\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(idString);\n} catch (IllegalArgumentException e) {\n    log.error(\"Bad response_correlation_id '{}'\", idString, e);\n    throw new ConfigException(\"Check response_correlation_id: must be a number >= -1 or 'PROTOTYPE'\", e);\n}","preventionTips":["Source correlation IDs from Aeron client futures, never from arbitrary negative sentinels.","Treat unsigned 64-bit IDs with Long.toUnsignedString to avoid negative wrap-around.","Reserve -1 (or the prototype keyword) for the special no-response case only."],"tags":["aeron","channel-uri","correlation-id","validation"],"backgroundTag":"value-out-of-range","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}