cilium/cilium · error

unknown protocol: %q

Error message

unknown protocol: %q

What it means

filterByProtocol accepts only a fixed allow-list of protocol names: L4 ('icmp', 'icmpv4', 'icmpv6', 'tcp', 'udp', 'sctp', 'vrrp', 'igmp') and L7 ('dns', 'http'). Anything else returns 'unknown protocol: %q', so an unrecognized name aborts filter construction.

Source

Thrown at pkg/hubble/filters/protocol.go:25

	"context"
	"fmt"
	"strings"

	flowpb "github.com/cilium/cilium/api/v1/flow"
	v1 "github.com/cilium/cilium/pkg/hubble/api/v1"
)

func filterByProtocol(protocols []string) (FilterFunc, error) {
	var l4Protocols, l7Protocols []string
	for _, p := range protocols {
		proto := strings.ToLower(p)
		switch proto {
		case "icmp", "icmpv4", "icmpv6", "tcp", "udp", "sctp", "vrrp", "igmp":
			l4Protocols = append(l4Protocols, proto)
		case "dns", "http":
			l7Protocols = append(l7Protocols, proto)
		default:
			return nil, fmt.Errorf("unknown protocol: %q", p)
		}
	}

	return func(ev *v1.Event) bool {
		l4 := ev.GetFlow().GetL4()
		for _, proto := range l4Protocols {
			switch proto {
			case "icmp":
				if l4.GetICMPv4() != nil || l4.GetICMPv6() != nil {
					return true
				}
			case "icmpv4":
				if l4.GetICMPv4() != nil {
					return true
				}
			case "icmpv6":
				if l4.GetICMPv6() != nil {
					return true

View on GitHub (pinned to ac7b90affa)

Solutions

1. Use one of the supported names, lowercase: icmp, icmpv4, icmpv6, tcp, udp, sctp, vrrp, igmp, dns, http
2. Normalize case and trim whitespace on user input before passing it as a filter
3. Check your Hubble version — the allow-list has grown over time; upgrade if you need newer protocols
4. Convert numeric protocol numbers to their names beforehand

Example fix

// before
ff := &flowpb.FlowFilter{Protocol: []string{"TLS"}}
// after
ff := &flowpb.FlowFilter{Protocol: []string{"tcp"}}

var validProtocols = map[string]bool{
	"icmp": true, "icmpv4": true, "icmpv6": true, "tcp": true, "udp": true,
	"sctp": true, "vrrp": true, "igmp": true, "dns": true, "http": true,
}
for _, p := range ff.GetProtocol() {
	if !validProtocols[strings.ToLower(strings.TrimSpace(p))] {
		return fmt.Errorf("unsupported protocol %q", p)
	}
}

fs, err := protoFilter.OnBuildFilter(ctx, ff)
if err != nil && strings.Contains(err.Error(), "unknown protocol") {
	return fmt.Errorf("see hubble docs for supported protocol names: %w", err)
}

When it happens

Trigger: Calling OnBuildFilter with FlowFilter Protocol entries such as 'TLS', 'ICMP ' (with whitespace), 'TCP' (uppercase), 'quic', or numeric protocol numbers ('6') — none of which are in the switch.

Common situations: Case-sensitivity mistakes (TCP vs tcp), assuming all IANA protocol names or numbers are supported, trying newer protocols (quic, http/2) not yet whitelisted by this Hubble version.

Related errors

• invalid protocol filter: %w
• invalid http status code filter: %w
• invalid filter, name must not be empty
• invalid node label filter: %w
• %q: invalid rune in pattern

AI-assisted analysis of cilium/cilium@ac7b90affa (2026-08-31). Data as JSON: /api/errors/19c0a0a790773d04. Report an issue: GitHub.