XTLS/Xray-core · error

Failed to build gRPC config.

Error message

Failed to build gRPC config.

What it means

Wrapper thrown when streamSettings contains grpcSettings whose Build() fails. The underlying gRPC error is chained with .Base(err); typical causes are an empty or malformed serviceName or multiMode incompatibilities. The detail lives in the base error.

Source

Thrown at infra/conf/transport_internet.go:158

		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()
		if err != nil {
			return nil, errors.New("Failed to build WebSocket config.").Base(err)
		}
		config.TransportSettings = append(config.TransportSettings, &internet.TransportConfig{
			ProtocolName: "websocket",
			Settings:     serial.ToTypedMessage(ts),
		})
	}
	if c.HTTPUPGRADESettings != nil {
		hs, err := c.HTTPUPGRADESettings.Build()

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Inspect the base error for the exact gRPC field.
2. Set a valid non-empty serviceName (e.g. "MyService").
3. Remove deprecated multiMode/userLevel extras and retest.

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

When it happens

Trigger: grpcSettings with a missing 'serviceName', a serviceName containing invalid path characters, or stale multiMode configs on a fork that changed gRPC behavior.

Common situations: Omitting serviceName when adding gRPC transport; copying serviceName with trailing whitespace or slashes from tutorials.

Related errors

• Failed to build RAW config.
• Failed to build XHTTP config.
• Failed to build mKCP 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/d057c426476110b6. Report an issue: GitHub.