XTLS/Xray-core · error

Failed to build mKCP config.

Error message

Failed to build mKCP config.

What it means

Wrapper thrown when streamSettings contains kcpSettings (mKCP transport) whose Build() fails. The concrete cause — invalid header type, bad seed, or malformed obfuscation parameters — is attached with .Base(err) and should be inspected rather than this generic message.

Source

Thrown at infra/conf/transport_internet.go:148

		})
	}
	if c.XHTTPSettings != nil {
		c.SplitHTTPSettings = c.XHTTPSettings
	}
	if c.SplitHTTPSettings != nil {
		hs, err := c.SplitHTTPSettings.Build()
		if err != nil {
			return nil, errors.New("Failed to build XHTTP config.").Base(err)
		}
		config.TransportSettings = append(config.TransportSettings, &internet.TransportConfig{
			ProtocolName: "splithttp",
			Settings:     serial.ToTypedMessage(hs),
		})
	}
	if c.KCPSettings != nil {
		ts, err := c.KCPSettings.Build()
		if err != nil {
			return nil, errors.New("Failed to build mKCP config.").Base(err)
		}
		config.TransportSettings = append(config.TransportSettings, &internet.TransportConfig{
			ProtocolName: "mkcp",
			Settings:     serial.ToTypedMessage(ts),
		})
	}
	if c.GRPCSettings != nil {
		gs, err := c.GRPCSettings.Build()
		if err != nil {
			return nil, errors.New("Failed to build gRPC config.").Base(err)
		}
		config.TransportSettings = append(config.TransportSettings, &internet.TransportConfig{
			ProtocolName: "grpc",
			Settings:     serial.ToTypedMessage(gs),
		})
	}
	if c.WSSettings != nil {
		ts, err := c.WSSettings.Build()

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Read the base error to find the failing mKCP field.
2. Set header.type to "none" and re-add obfuscation step by step.
3. Regenerate or simplify the seed value.

if _, err := streamCfg.Build(); err != nil {
    if strings.Contains(err.Error(), "Failed to build mKCP config") {
        return fmt.Errorf("mkcp settings invalid: %w", errors.Unwrap(err))
    }
}

When it happens

Trigger: A kcpSettings block with an unknown 'header.type', an invalid 'seed' for sreno header, or non-numeric mtu/tti values.

Common situations: Old mKCP configs using header types removed in this fork; seeds containing characters outside the expected alphabet.

Related errors

• Failed to build RAW config.
• Failed to build XHTTP config.
• Failed to build gRPC config.
• Failed to build WebSocket config.
• Failed to build HTTPUpgrade config.

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