cloudflare/cloudflared · error

invalid connection override: %s

Error message

invalid connection override: %s

What it means

The ssh carrier command supports --connect-to / connection override strings with specific forms (host:port, or SNI overrides like 'sni:host'). When the override value does not match any known pattern, the switch's default branch returns 'invalid connection override'. It is a strict format validation of user-supplied connection options.

Source

Thrown at cmd/cloudflared/access/carrier.go:114

		IsFedramp: c.Bool(fedrampFlag),
	}

	if connectTo := c.String(sshConnectTo); connectTo != "" {
		parts := strings.Split(connectTo, ":")
		switch len(parts) {
		case 1:
			options.OriginURL = fmt.Sprintf("https://%s", parts[0])
		case 2:
			options.OriginURL = fmt.Sprintf("https://%s:%s", parts[0], parts[1])
		case 3:
			options.OriginURL = fmt.Sprintf("https://%s:%s", parts[2], parts[1])
			options.TLSClientConfig = &tls.Config{
				InsecureSkipVerify: true, // #nosec G402
				ServerName:         parts[0],
			}
			log.Warn().Msgf("Using insecure SSL connection because SNI overridden to %s", parts[0])
		default:
			return fmt.Errorf("invalid connection override: %s", connectTo)
		}
	}

	// we could add a cmd line variable for this bool if we want the SOCK5 server to be on the client side
	wsConn := carrier.NewWSConnection(log)

	if c.NArg() > 0 || c.IsSet(sshURLFlag) {
		forwarder, err := config.ValidateUrl(c, true)
		if err != nil {
			log.Err(err).Msg("Error validating origin URL")
			return errors.Wrap(err, "error validating origin URL")
		}
		log.Info().Str(LogFieldHost, forwarder.Host).Msg("Start Websocket listener")
		err = carrier.StartForwarder(wsConn, forwarder.Host, shutdownC, options)
		if err != nil {
			log.Err(err).Msg("Error on Websocket listener")
		}
		return err

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Use the accepted formats: hostname, hostname:port, or sni:hostname for SNI override; remove schemes and extra colons.
2. Check `cloudflared access ssh --help` for the exact connect-to syntax of your version.
3. If you intended an SNI override, write it as `sni:<hostname>`; the insecure-SSL branch above handles exactly that form.
4. Validate the value in scripts (regex on host[:port]) before passing it to cloudflared.

Example fix

// before
$ cloudflared access ssh --hostname example.com --connect-to https://example.com:8443
// after
$ cloudflared access ssh --hostname example.com --connect-to example.com:8443

var connectToRe = regexp.MustCompile(`^(sni:[^:]+$|[^:]+(:\d+)?)$`)
if !connectToRe.MatchString(value) {
	return fmt.Errorf("connect-to must be host[:port] or sni:host, got %q", value)
}

When it happens

Trigger: Running `cloudflared access ssh --connect-to <value>` (or equivalent carrier invocation) with a value in an unrecognized format — e.g. too many/few colon-separated parts, or an unknown override prefix instead of the supported sni: form.

Common situations: Copy-pasting destination syntax from other tools (like ssh -L style specs); adding a scheme (https://host) where only host[:port] or sni:host is accepted; typos in the sni: prefix such as 'sni.' or 'SNI:'.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

• not a valid host
• no input provided
• Invalid CIDR supplied for %s
• failed to parse as URL: %w
• Couldn't decode tunnel secret from base64

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