{"record":{"id":"e79c22e8a4862fc4","repo":"aeron-io/aeron","slug":"mtu-greater-than-so-sndbuf-for-channel-mtu-mtulength-so","errorCode":null,"errorMessage":"MTU greater than SO_SNDBUF for channel: mtu=<mtuLength> so-sndbuf=<channelSocketSndbufLength> existingChannel=<existingChannel> channel=<channel>","messagePattern":"MTU greater than SO_SNDBUF for channel: mtu=<mtuLength> so-sndbuf=<channelSocketSndbufLength> existingChannel=<existingChannel> channel=<channel>","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/PublicationParams.java","lineNumber":383,"sourceCode":"    {\n        if (params.spiesSimulateConnection != existingSpiesSimulateConnection)\n        {\n            throw new IllegalStateException(\"existing publication has different spiesSimulateConnection: existing=\" +\n                existingSpiesSimulateConnection + \" requested=\" + params.spiesSimulateConnection +\n                \" existingChannel=\" + existingChannel + \" channel=\" + channel);\n        }\n    }\n\n    static void validateMtuForSndbuf(\n        final PublicationParams params,\n        final int channelSocketSndbufLength,\n        final MediaDriver.Context ctx,\n        final String channel,\n        final String existingChannel)\n    {\n        if (0 != channelSocketSndbufLength && params.mtuLength > channelSocketSndbufLength)\n        {\n            throw new IllegalStateException(\n                \"MTU greater than SO_SNDBUF for channel: mtu=\" + params.mtuLength +\n                \" so-sndbuf=\" + channelSocketSndbufLength +\n                (null == existingChannel ? \"\" : (\" existingChannel=\" + existingChannel)) +\n                \" channel=\" + channel);\n        }\n        else if (0 == channelSocketSndbufLength && params.mtuLength > ctx.osDefaultSocketSndbufLength())\n        {\n            throw new IllegalStateException(\n                \"MTU greater than SO_SNDBUF for channel: mtu=\" + params.mtuLength +\n                \" so-sndbuf=\" + ctx.osDefaultSocketSndbufLength() + \" (OS default)\" +\n                (null == existingChannel ? \"\" : (\" existingChannel=\" + existingChannel)) +\n                \" channel=\" + channel);\n        }\n    }\n\n    private void getLingerTimeoutNs(final ChannelUri channelUri, final MediaDriver.Context ctx)\n    {\n        final String lingerParam = channelUri.get(LINGER_PARAM_NAME);","sourceCodeStart":365,"sourceCodeEnd":401,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/PublicationParams.java#L365-L401","documentation":"The channel URI sets an explicit socket-sndbuf (SO_SNDBUF) smaller than the publication MTU; Aeron throws IllegalStateException because each datagram must fit in the socket send buffer or sends would fail with EMSGSIZE. Thrown by validateMtuForSndbuf when validating publication params.","triggerScenarios":"Adding a network publication whose URI has both `mtu=` (e.g. 16384) and `so-sndbuf=` smaller than the MTU, or a `session-id` tag referencing an existing publication with a larger MTU.","commonSituations":"Tuning for throughput by raising MTU while leaving a low so-sndbuf; copying channel strings between hosts with different buffer settings; session-id tagged publications inheriting a large MTU.","solutions":["Raise the channel's so-sndbuf URI value to at least the mtu length","Lower the mtu URI value to at most so-sndbuf","Remove the explicit so-sndbuf so the OS default check applies instead","Check the driver's osDefaultSocketSndbufLength via error 652 path if sndbuf is 0"],"exampleFix":"// before\n\"aeron:udp?endpoint=localhost:40456|mtu=16384|so-sndbuf=8192\"\n// after\n\"aeron:udp?endpoint=localhost:40456|mtu=16384|so-sndbuf=131072\"","handlingStrategy":"validation","validationCode":"long sndbuf = getUriParam(uri, \"so-sndbuf\", -1);\nint mtu = getUriParam(uri, \"mtu\", 4096);\nif (sndbuf > 0 && mtu > sndbuf) throw new IllegalArgumentException(\"mtu must be <= so-sndbuf\");","typeGuard":null,"tryCatchPattern":"try { publication = aeron.addPublication(uri, streamId); }\ncatch (IllegalStateException e) {\n    if (e.getMessage().contains(\"MTU greater than SO_SNDBUF\")) {\n        throw new ConfigurationException(\"Channel \" + uri + \" has mtu exceeding so-sndbuf\", e);\n    } throw e;\n}","preventionTips":["Derive so-sndbuf as max(mtu, defaultSndbuf) when generating URIs","Keep mtu and so-sndbuf in the same config block so they are reviewed together","Test channel configs with a startup validation pass before adding publications"],"tags":["aeron","mtu","udp","buffer-size"],"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"}