cloudflare/cloudflared · error

%s has unknown TLS settings

Error message

%s has unknown TLS settings

What it means

Each supported edge connection Protocol must return non-nil TLSSettings(); if a protocol in connection.ProtocolList yields nil, prepareTunnelConfig aborts because it cannot build the edge TLS config for that protocol. This indicates an internal inconsistency between the protocol registry and its TLS metadata.

Source

Thrown at cmd/cloudflared/tunnel/configuration.go:158

	tags = append(tags, pogs.Tag{Name: "ID", Value: clientConfig.ConnectorID.String()})

	cfg := config.GetConfiguration()
	ingressRules, err := ingress.ParseIngressFromConfigAndCLI(cfg, c, log)
	if err != nil {
		return nil, nil, err
	}

	protocolSelector, err := connection.NewProtocolSelector(transportProtocol, log)
	if err != nil {
		return nil, nil, err
	}
	log.Info().Msgf("Initial protocol %s", protocolSelector.Current())

	edgeTLSConfigs := make(map[connection.Protocol]*tls.Config, len(connection.ProtocolList))
	for _, p := range connection.ProtocolList {
		tlsSettings := p.TLSSettings()
		if tlsSettings == nil {
			return nil, nil, fmt.Errorf("%s has unknown TLS settings", p)
		}
		edgeTLSConfig, err := tlsconfig.CreateTunnelConfig(c.String(flags.CACert), tlsSettings.ServerName)
		if err != nil {
			return nil, nil, errors.Wrap(err, "unable to create TLS config to connect with edge")
		}
		if len(tlsSettings.NextProtos) > 0 {
			edgeTLSConfig.NextProtos = tlsSettings.NextProtos
		}
		edgeTLSConfigs[p] = edgeTLSConfig
	}

	gracePeriod, err := gracePeriod(c)
	if err != nil {
		return nil, nil, err
	}
	edgeIPVersion, err := parseConfigIPVersion(c.String(flags.EdgeIpVersion))
	if err != nil {
		return nil, nil, err

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Update cloudflared to an official release — this should never occur on stock builds.
2. If building a fork, implement TLSSettings() for every protocol added to connection.ProtocolList.
3. Report the issue with the protocol name from the message if it reproduces on an official binary.

Example fix

// before (fork)
func (p Protocol) TLSSettings() *TLSSettings { if p == MyProto { return nil } ... }
// after
func (p Protocol) TLSSettings() *TLSSettings { if p == MyProto { return &TLSSettings{ServerName: "...", NextProtos: []string{"..."}} } ... }

// Only stock protocol values are safe: quic, http2
[[ "$PROTOCOL" =~ ^(quic|http2|auto)$ ]] || { echo "unsupported protocol $PROTOCOL"; exit 1; }

When it happens

Trigger: Iterating connection.ProtocolList during prepareTunnelConfig when a registered protocol (e.g. a newly added or experimental protocol) has no TLSSettings mapping — essentially a build/registry bug, not user configuration.

Common situations: Custom forks or patched builds where a new connection.Protocol was added to ProtocolList but TLSSettings() was not updated; mismatched vendored copies of the connection package.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

• internal error: unsupported connection type
• invalid datagram type expected
• namedTunnel is nil
• Received unknown connection type: %s
• unknown protocol %s, %s

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