cloudflare/cloudflared · error

unknown protocol %s, %s

Error message

unknown protocol %s, %s

What it means

NewProtocolSelector maps the --protocol flag value to a protocolSelector. Accepted values are quic, http2, and auto. Any other string falls through to `unknown protocol %s, %s` with the list of valid values appended (AvailableProtocolFlagMessage). It fails fast at tunnel startup before any connection attempt.

Source

Thrown at connection/protocol.go:136

func NewProtocolSelector(
	protocolFlag string,
	log *zerolog.Logger,
) (ProtocolSelector, error) {
	// If the user picks a protocol, then we stick to it no matter what.
	switch protocolFlag {
	case "h2mux":
		// Any users still requesting h2mux will be upgraded to http2 instead
		log.Warn().Msg("h2mux is no longer a supported protocol: upgrading edge connection to http2. Please remove '--protocol h2mux' from runtime arguments to remove this warning.")
		return &protocolSelector{current: HTTP2}, nil
	case QUIC.String():
		return &protocolSelector{current: QUIC}, nil
	case HTTP2.String():
		return &protocolSelector{current: HTTP2}, nil
	case AutoSelectFlag:
		return &protocolSelector{current: QUIC, allowFallback: true}, nil
	}

	return nil, fmt.Errorf("unknown protocol %s, %s", protocolFlag, AvailableProtocolFlagMessage)
}

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Set --protocol to one of: quic, http2, or auto (or remove the flag to use auto)
2. Replace removed values like h2mux with http2
3. Check both the config file `protocol:` key and the CLI flag, since config file values also flow here
4. Run `cloudflared tunnel --help` to see the accepted protocol values for your version

Example fix

# before (config.yml)
protocol: h2mux
# after
protocol: quic

valid := map[string]bool{"quic": true, "http2": true, "auto": true}
if p := cfg.Protocol; p != "" && !valid[strings.ToLower(p)] {
    return fmt.Errorf("protocol %q is invalid; use quic, http2, or auto", p)
}

When it happens

Trigger: prepareTunnelConfig (or tests) calls NewProtocolSelector with a --protocol flag value not in {quic, http2, auto}, e.g. a typo (`quic2`), old value (`h2mux` removed in newer versions), or an empty-but-set string.

Common situations: Config files carried over from older cloudflared versions still setting `protocol: h2mux`, typos in the --protocol CLI flag, or automation scripts using invalid values.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• --unix-socket must be used exclusively.
• Specified origin urls using both --url and argument. Decide
• option type Generic not supported
• unable to find config file
• An api-url was not provided for the Cloudflare API client

AI-assisted analysis of cloudflare/cloudflared@2253eeeb25 (2026-09-06). Data as JSON: /api/errors/662b2f99c879daee. Report an issue: GitHub.