{"record":{"id":"feb40c478f4fea4c","repo":"aeron-io/aeron","slug":"initial-window-greater-than-so-rcvbuf-for-channel-rcv-wnd-feb40c","errorCode":null,"errorMessage":"Initial window greater than SO_RCVBUF for channel: rcv-wnd=<receiverWindowLength> so-rcvbuf=<osDefaultSocketRcvbufLength> (OS default) existingChannel=<existingChannel> channel=<channel>","messagePattern":"Initial window greater than SO_RCVBUF for channel: rcv-wnd=<receiverWindowLength> so-rcvbuf=<osDefaultSocketRcvbufLength> \\(OS default\\) existingChannel=<existingChannel> channel=<channel>","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/SubscriptionParams.java","lineNumber":184,"sourceCode":"    }\n\n    static void validateInitialWindowForRcvBuf(\n        final SubscriptionParams params,\n        final String channel,\n        final int channelSocketRcvbufLength,\n        final MediaDriver.Context ctx,\n        final String existingChannel)\n    {\n        if (0 != channelSocketRcvbufLength && params.receiverWindowLength > channelSocketRcvbufLength)\n        {\n            throw new IllegalStateException(\n                \"Initial window greater than SO_RCVBUF for channel: rcv-wnd=\" + params.receiverWindowLength +\n                \" so-rcvbuf=\" + channelSocketRcvbufLength +\n                (null == existingChannel ? \"\" : (\" existingChannel=\" + existingChannel)) + \" channel=\" + channel);\n        }\n        else if (0 == channelSocketRcvbufLength && params.receiverWindowLength > ctx.osDefaultSocketRcvbufLength())\n        {\n            throw new IllegalStateException(\n                \"Initial window greater than SO_RCVBUF for channel: rcv-wnd=\" + params.receiverWindowLength +\n                \" so-rcvbuf=\" + ctx.osDefaultSocketRcvbufLength() + \" (OS default)\" +\n                (null == existingChannel ? \"\" : (\" existingChannel=\" + existingChannel)) + \" channel=\" + channel);\n        }\n    }\n\n    public String toString()\n    {\n        return \"SubscriptionParams\" +\n            \"\\n{\" +\n            \"\\n    initialTermId=\" + initialTermId +\n            \"\\n    termId=\" + termId +\n            \"\\n    termOffset=\" + termOffset +\n            \"\\n    sessionId=\" + sessionId +\n            \"\\n    hasJoinPosition=\" + hasJoinPosition +\n            \"\\n    hasSessionId=\" + hasSessionId +\n            \"\\n    isReliable=\" + isReliable +\n            \"\\n    isRejoin=\" + isRejoin +","sourceCodeStart":166,"sourceCodeEnd":202,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/SubscriptionParams.java#L166-L202","documentation":"When the channel URI does not set so-rcvbuf (value 0, meaning OS default), the receiver window must still not exceed the OS default socket receive buffer (ctx.osDefaultSocketRcvbufLength()). The driver throws IllegalStateException naming the OS default so the user knows which limit was exceeded.","triggerScenarios":"Adding a subscription with a large receiver-window-length (or a driver-side default initial-window-endpoint exceeding OS defaults) on a channel URI without so-rcvbuf, when rcv-wnd > osDefaultSocketRcvbufLength.","commonSituations":"High-throughput deployments raising initial window without configuring so-rcvbuf; containers/hosts with small net.core.rmem_max making the OS default tiny; migrating configs to machines with different OS defaults.","solutions":["Set so-rcvbuf in the channel URI to at least the desired receiver window.","Lower receiver-window-length to fit under the OS default buffer.","Raise OS limits: net.core.rmem_max and net.core.rmem_default via sysctl, then restart.","Set MediaDriver.Context osDefaultSocketRcvbufLength probing appropriately by ensuring the OS buffers are large before driver start."],"exampleFix":"// before\n\"aeron:udp?endpoint=localhost:40456|rcv-wnd=8388608\" // relies on OS default\n// after\n\"aeron:udp?endpoint=localhost:40456|rcv-wnd=8388608|so-rcvbuf=8388608\" // or raise net.core.rmem_max","handlingStrategy":"validation","validationCode":"if (soRcvbuf == 0 && rcvWnd > osDefaultRcvbuf) {\n    throw new IllegalArgumentException(\"rcv-wnd (\" + rcvWnd + \") exceeds OS default SO_RCVBUF (\" + osDefaultRcvbuf + \"); set so-rcvbuf or raise rmem_max\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Explicitly set so-rcvbuf for high-throughput channels instead of relying on OS defaults.","Verify net.core.rmem_max/rmem_default on each host/container before deploying large windows.","Re-check OS defaults after environment or kernel changes."],"tags":["aeron","network","os-tuning","socket-buffer"],"backgroundTag":"invalid-config-value","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}