What causes "unsupported message codec" in fatedier/frp?

Always include wire.MessageCodecJSON in ClientHello.Capabilities.Message.Codecs — in practice send [MessageCodecJSON].

unsupported message codec

Error message

unsupported message codec

What it means

Thrown by ValidateClientHello when the client's advertised message codec list does not include MessageCodecJSON. JSON is the only message codec this implementation supports, so a ClientHello without it cannot be served. This runs on the server side when a client first connects.

Source

Thrown at pkg/proto/wire/wire.go:247

}

func DefaultServerHello() ServerHello {
	return ServerHello{
		Selected: ServerSelection{
			Message: MessageSelection{
				Codec: MessageCodecJSON,
			},
		},
	}
}

func Supports(list []string, value string) bool {
	return slices.Contains(list, value)
}

func ValidateClientHello(h ClientHello) error {
	if !Supports(h.Capabilities.Message.Codecs, MessageCodecJSON) {
		return fmt.Errorf("unsupported message codec")
	}
	return ValidateCryptoCapabilities(h.Capabilities.Crypto)
}

View on GitHub (pinned to 6c8a8d0a97)

Solutions

Always include wire.MessageCodecJSON in ClientHello.Capabilities.Message.Codecs — in practice send [MessageCodecJSON].
Fix hand-written ClientHello fixtures to populate the full capabilities struct.
Align custom clients with the stock frp client's hello construction.

Example fix

// before
hello.Capabilities.Message.Codecs = nil

// after
hello.Capabilities.Message.Codecs = []string{wire.MessageCodecJSON}

Defensive patterns

Strategy: validation

Validate before calling

hello.Capabilities.Message.Codecs = []string{wire.MessageCodecJSON}
if err := wire.ValidateClientHello(hello); err != nil {
    return fmt.Errorf("hello rejected: %w", err)
}

Prevention

Populate capabilities from library constants, never from config strings.
Run ValidateClientHello client-side in a unit test to catch fixture drift.

When it happens

Trigger: Client sends ClientHello with Capabilities.Message.Codecs empty or containing only non-JSON entries (e.g. ["msgpack"]); server calls ValidateClientHello during handshake acceptance.

Common situations: Third-party or custom clients omitting the Codecs field; older protocol versions that had no codec negotiation; test fixtures built by hand without the codec list.

Related errors

AI-assisted analysis of fatedier/frp@6c8a8d0a97 (2026-08-15). Data as JSON: /api/errors/d8d6549f3472ddd3. Report an issue: GitHub.