XTLS/Xray-core · error

Mtu must be at least 21

Error message

Mtu must be at least 21

What it means

Thrown by KCPConfig.Build() when building an mKCP transport config whose Mtu value is below 21. mKCP needs a minimum MTU of 21 bytes to fit its packet header (conv, cmd, frg, wnd, ts, sn, una fields), so anything smaller cannot carry a valid KCP frame. The check runs after JSON defaults are applied, so the value used is the effective one.

Source

Thrown at infra/conf/transport_method.go:563

	}
	if c.Tti != nil {
		config.Tti = *c.Tti
	}
	if c.UpCap != nil {
		config.UplinkCapacity = *c.UpCap
	}
	if c.DownCap != nil {
		config.DownlinkCapacity = *c.DownCap
	}
	if c.CwndMultiplier != nil {
		config.CwndMultiplier = *c.CwndMultiplier
	}
	if c.MaxSendingWindow != nil {
		config.MaxSendingWindow = *c.MaxSendingWindow
	}

	if config.Mtu < 21 {
		return nil, errors.New("Mtu must be at least 21").AtError()
	}
	if config.Tti < 10 || config.Tti > 1000 {
		return nil, errors.New("invalid mKCP TTI: ", c.Tti).AtError()
	}
	if config.CwndMultiplier < 1 {
		return nil, errors.New("CwndMultiplier must be at least 1").AtError()
	}
	if config.GetSendingBufferSize() == 0 {
		return nil, errors.New("MaxSendingWindow must be >= Mtu").AtError()
	}

	return config, nil
}

type GRPCConfig struct {
	Authority           string `json:"authority"`
	ServiceName         string `json:"serviceName"`
	MultiMode           bool   `json:"multiMode"`

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Set kcpSettings.mtu to 21 or higher (1200-1400 is the usual range).
2. Remove the mtu field entirely to accept the default.
3. If a generator/template produced the config, fix it and re-emit.

Example fix

// before
"kcpSettings": { "mtu": 20, "tti": 50 }
// after
"kcpSettings": { "mtu": 1350, "tti": 50 }

// before building the transport
if kcp.Mtu != nil && *kcp.Mtu < 21 {
    return fmt.Errorf("mKCP mtu %d below minimum 21", *kcp.Mtu)
}

err := json.Unmarshal(raw, &cfg)
if err == nil {
    if _, err = cfg.Build(); err != nil {
        if strings.Contains(err.Error(), "Mtu must be at least 21") {
            log.Printf("config error: raise kcpSettings.mtu to >= 21")
        }
    }
}

When it happens

Trigger: Setting "mtu" (e.g. 1350) below 21 in the kcpSettings block of an outbound/inbound streamSettings, or omitting it while a custom value of 0/20 leaks in from a template or generator.

Common situations: Copy-pasted client configs with a truncated mtu value, config generators emitting mtu: 0, or users trying to 'tune' mKCP down for overhead and going below the protocol floor.

Related errors

• invalid mKCP TTI:
• CwndMultiplier must be at least 1
• MaxSendingWindow must be >= Mtu
• invalid header
• gecko: invalid min/max packet size

AI-assisted analysis of XTLS/Xray-core@7d214f8b09 (2026-08-15). Data as JSON: /api/errors/47fa17b827072de8. Report an issue: GitHub.