{"record":{"id":"6052119073012fb2","repo":"aeron-io/aeron","slug":"mtu-greater-than-so-sndbuf-for-channel-mtu-mtulength-so-605211","errorCode":null,"errorMessage":"MTU greater than SO_SNDBUF for channel: mtu=<mtuLength> so-sndbuf=<osDefaultSocketSndbufLength> (OS default) existingChannel=<existingChannel> channel=<channel>","messagePattern":"MTU greater than SO_SNDBUF for channel: mtu=<mtuLength> so-sndbuf=<osDefaultSocketSndbufLength> \\(OS default\\) existingChannel=<existingChannel> channel=<channel>","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/PublicationParams.java","lineNumber":391,"sourceCode":"\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);\n        if (null != lingerParam)\n        {\n            lingerTimeoutNs = SystemUtil.parseDuration(LINGER_PARAM_NAME, lingerParam);\n        }\n        else\n        {\n            lingerTimeoutNs = ctx.publicationLingerTimeoutNs();\n        }","sourceCodeStart":373,"sourceCodeEnd":409,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/PublicationParams.java#L373-L409","documentation":"Same rule as the explicit so-sndbuf case: when the channel does not specify so-sndbuf, Aeron compares the MTU against the OS default socket send buffer (osDefaultSocketSndbufLength) and throws IllegalStateException if MTU exceeds it. The '(OS default)' marker in the message indicates this branch.","triggerScenarios":"Adding a network publication with a large `mtu=` URI value while the channel has no `so-sndbuf` param and the OS default SNDBUF (net.core.wmem_default) is smaller than the MTU.","commonSituations":"Linux hosts with default wmem_default (~212992) are usually fine, but constrained containers/VMs or explicitly shrunk sysctl defaults break large-MTU configs; cloud instances with low defaults.","solutions":["Lower the mtu URI value to fit the OS default send buffer","Increase the OS default: sysctl -w net.core.wmem_default=<value> (and persist in /etc/sysctl.conf)","Add an explicit so-sndbuf to the channel URI at least equal to the MTU","Verify with `cat /proc/sys/net/core/wmem_default` before choosing MTU"],"exampleFix":"// before\n\"aeron:udp?endpoint=localhost:40456|mtu=8948\"  // OS default SNDBUF is 4096\n// after (either)\n\"aeron:udp?endpoint=localhost:40456|mtu=8948|so-sndbuf=16384\"\n// or shell: sysctl -w net.core.wmem_default=16384","handlingStrategy":"validation","validationCode":"long osDefault = Long.parseLong(\n    java.nio.file.Files.readString(java.nio.file.Path.of(\"/proc/sys/net/core/wmem_default\")).trim());\nif (mtu > osDefault && uriLacksParam(\"so-sndbuf\")) throw new IllegalArgumentException(\"mtu exceeds OS default SNDBUF\");","typeGuard":null,"tryCatchPattern":"try { publication = aeron.addPublication(uri, streamId); }\ncatch (IllegalStateException e) {\n    if (e.getMessage().contains(\"(OS default)\")) {\n        throw new ConfigurationException(\"Increase net.core.wmem_default or set so-sndbuf in the channel URI\", e);\n    } throw e;\n}","preventionTips":["Check net.core.wmem_default on deployment hosts before choosing MTU","Set an explicit so-sndbuf so behavior is OS-independent","Document required sysctls in deployment manifests"],"tags":["aeron","mtu","udp","os-tuning"],"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"}