slackhq/nebula · error

entry %v.mtu in tun.routes is below 500: %v

Error message

entry %v.mtu in tun.routes is below 500: %v

What it means

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.

Source

Thrown at overlay/route.go:108

		if !ok {
			return nil, fmt.Errorf("entry %v in tun.routes is invalid", i+1)
		}

		rMtu, ok := m["mtu"]
		if !ok {
			return nil, fmt.Errorf("entry %v.mtu in tun.routes is not present", i+1)
		}

		mtu, ok := rMtu.(int)
		if !ok {
			mtu, err = strconv.Atoi(rMtu.(string))
			if err != nil {
				return nil, fmt.Errorf("entry %v.mtu in tun.routes is not an integer: %v", i+1, err)
			}
		}

		if mtu < 500 {
			return nil, fmt.Errorf("entry %v.mtu in tun.routes is below 500: %v", i+1, mtu)
		}

		rRoute, ok := m["route"]
		if !ok {
			return nil, fmt.Errorf("entry %v.route in tun.routes is not present", i+1)
		}

		r := Route{
			Install: true,
			MTU:     mtu,
		}

		r.Cidr, err = netip.ParsePrefix(fmt.Sprintf("%v", rRoute))
		if err != nil {
			return nil, fmt.Errorf("entry %v.route in tun.routes failed to parse: %v", i+1, err)
		}

		found := false

View on GitHub (pinned to dd8f660c0a)

Solutions

1. Raise mtu to at least 500 (typical safe values are 1300-1400 for overlay tunnels)
2. Do not use 0 or negative values; there is no auto-detect — pick an explicit value
3. If troubleshooting fragmentation, reduce MTU gradually but stay >= 500
4. Use the reported entry index to find the offending entry

Example fix

// before
- mtu: 300
  route: 10.0.0.0/24
// after
- mtu: 1300
  route: 10.0.0.0/24

mtu := m["mtu"].(int)
if mtu < 500 {
    return fmt.Errorf("tun.routes mtu %d must be >= 500", mtu)
}

When it happens

Trigger: getAllRoutesFromConfig reads an entry like {mtu: 400, route: ...} or mtu: "300"; also zero-valued mtu fields coming from unset template variables.

Common situations: Copy-pasting MTU values from other tooling with different minimums; assuming 0 means 'auto'; experimenting with very low MTUs to work around fragmentation issues.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Empty configuration
• group should contain a single value, an array with more than
• stats.host can not be empty
• stats.listen should not be empty
• stats.path should not be empty

AI-assisted analysis of slackhq/nebula@dd8f660c0a (2026-09-03). Data as JSON: /api/errors/d306755f9f4ef0d3. Report an issue: GitHub.