{"record":{"id":"d306755f9f4ef0d3","repo":"slackhq/nebula","slug":"entry-v-mtu-in-tun-routes-is-below-500-v","errorCode":null,"errorMessage":"entry %v.mtu in tun.routes is below 500: %v","messagePattern":"entry (.+?)\\.mtu in tun\\.routes is below 500: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"overlay/route.go","lineNumber":108,"sourceCode":"\t\tif !ok {\n\t\t\treturn nil, fmt.Errorf(\"entry %v in tun.routes is invalid\", i+1)\n\t\t}\n\n\t\trMtu, ok := m[\"mtu\"]\n\t\tif !ok {\n\t\t\treturn nil, fmt.Errorf(\"entry %v.mtu in tun.routes is not present\", i+1)\n\t\t}\n\n\t\tmtu, ok := rMtu.(int)\n\t\tif !ok {\n\t\t\tmtu, err = strconv.Atoi(rMtu.(string))\n\t\t\tif err != nil {\n\t\t\t\treturn nil, fmt.Errorf(\"entry %v.mtu in tun.routes is not an integer: %v\", i+1, err)\n\t\t\t}\n\t\t}\n\n\t\tif mtu < 500 {\n\t\t\treturn nil, fmt.Errorf(\"entry %v.mtu in tun.routes is below 500: %v\", i+1, mtu)\n\t\t}\n\n\t\trRoute, ok := m[\"route\"]\n\t\tif !ok {\n\t\t\treturn nil, fmt.Errorf(\"entry %v.route in tun.routes is not present\", i+1)\n\t\t}\n\n\t\tr := Route{\n\t\t\tInstall: true,\n\t\t\tMTU:     mtu,\n\t\t}\n\n\t\tr.Cidr, err = netip.ParsePrefix(fmt.Sprintf(\"%v\", rRoute))\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"entry %v.route in tun.routes failed to parse: %v\", i+1, err)\n\t\t}\n\n\t\tfound := false","sourceCodeStart":90,"sourceCodeEnd":126,"githubUrl":"https://github.com/slackhq/nebula/blob/dd8f660c0ac37903ec4080ca4d3c861ba9342ceb/overlay/route.go#L90-L126","documentation":"The parsed mtu of a tun.routes entry is below the minimum allowed value of 500. After conversion, parseRoutes enforces mtu >= 500 because smaller MTUs break the tunnel's packet handling. The offending value is included in the message.","triggerScenarios":"getAllRoutesFromConfig reads an entry like {mtu: 400, route: ...} or mtu: \"300\"; also zero-valued mtu fields coming from unset template variables.","commonSituations":"Copy-pasting MTU values from other tooling with different minimums; assuming 0 means 'auto'; experimenting with very low MTUs to work around fragmentation issues.","solutions":["Raise mtu to at least 500 (typical safe values are 1300-1400 for overlay tunnels)","Do not use 0 or negative values; there is no auto-detect — pick an explicit value","If troubleshooting fragmentation, reduce MTU gradually but stay >= 500","Use the reported entry index to find the offending entry"],"exampleFix":"// before\n- mtu: 300\n  route: 10.0.0.0/24\n// after\n- mtu: 1300\n  route: 10.0.0.0/24","handlingStrategy":"validation","validationCode":"mtu := m[\"mtu\"].(int)\nif mtu < 500 {\n    return fmt.Errorf(\"tun.routes mtu %d must be >= 500\", mtu)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep MTU >= 500 (1300-1400 is typical for tunnels)","Do not set mtu to 0 expecting auto-detection","If fighting fragmentation, lower MTU gradually but stay above 500","Document chosen MTU per deployment to avoid regressions"],"tags":["config","validation"],"backgroundTag":"schema-validation-failed","analyzedSha":"dd8f660c0ac37903ec4080ca4d3c861ba9342ceb","analyzedAt":"2026-09-03T11:13:55.444Z","contentChangedAt":"2026-09-03T11:13:55.444Z","schemaVersion":2},"datasetVersion":"2026-09-10T17:17:09.494Z"}