What causes "invalid HTTPS proxy address: %w" in larksuite/cli?

Set the proxy address with an explicit port, e.g. https://proxy.example.com:443

invalid HTTPS proxy address: %w

Error message

invalid HTTPS proxy address: %w

What it means

When tunneling through an HTTPS proxy, the transport dials the proxy and then performs a TLS handshake with it, deriving the SNI from the proxy address. This error wraps net.SplitHostPort failing on the configured proxy address, meaning the address lacks a host:port form (or is malformed), so the proxy TLS server name cannot be determined.

Source

Thrown at internal/validate/url.go:438

}

func configureHTTPSProxyTLSDialer(transport, source *http.Transport) {
	if transport.DialTLSContext != nil || transport.DialTLS != nil {
		return
	}

	proxyTLSConfig := cloneDownloadTLSConfig(source.TLSClientConfig)
	transport.DialTLSContext = func(ctx context.Context, network, addr string) (net.Conn, error) {
		rawConn, err := dialDownloadProxy(ctx, source, network, addr)
		if err != nil {
			return nil, err
		}

		config := proxyTLSConfig.Clone()
		serverName, _, splitErr := net.SplitHostPort(addr)
		if splitErr != nil {
			rawConn.Close()
			return nil, fmt.Errorf("invalid HTTPS proxy address: %w", splitErr)
		}
		config.ServerName = serverName
		tlsConn := tls.Client(rawConn, config)
		handshakeCtx := ctx
		cancel := func() {}
		if source.TLSHandshakeTimeout > 0 {
			handshakeCtx, cancel = context.WithTimeout(ctx, source.TLSHandshakeTimeout)
		}
		defer cancel()
		if err := tlsConn.HandshakeContext(handshakeCtx); err != nil {
			rawConn.Close()
			return nil, err
		}
		return tlsConn, nil
	}
}

func dialDownloadProxy(ctx context.Context, source *http.Transport, network, addr string) (net.Conn, error) {

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Set the proxy address with an explicit port, e.g. https://proxy.example.com:443
For IPv6 proxies, bracket the host: [::1]:8443
Check HTTPS_PROXY/HTTP_PROXY environment variables and CLI proxy config for a missing :port
Fix the wrapped SplitHostPort cause shown in the error (%w) for the exact malformed address

Example fix

// before
proxyURL, _ := url.Parse("https://proxy.corp.internal") // no port
// after
proxyURL, _ := url.Parse("https://proxy.corp.internal:443")

Defensive patterns

Strategy: validation

Validate before calling

// Validate the proxy address before configuring the client
u, err := url.Parse(proxyCfg)
if err != nil { return err }
if _, port, serr := net.SplitHostPort(u.Host); serr != nil || port == "" {
    return fmt.Errorf("HTTPS proxy must be host:port, got %q", proxyCfg)
}

Type guard

func validProxyAddr(u *url.URL) bool {
    host, port, err := net.SplitHostPort(u.Host)
    return err == nil && host != "" && port != ""
}

Try / catch

if err != nil && strings.Contains(err.Error(), "invalid HTTPS proxy address") {
    return fmt.Errorf("fix proxy config to host:port form: %w", err)
}

Prevention

Always include an explicit port in proxy configuration (https://proxy:443)
Bracket IPv6 proxy hosts: [2001:db8::1]:8443
Validate HTTPS_PROXY env values at config-load time
Trim whitespace when reading proxy settings from config/env

When it happens

Trigger: The HTTPS proxy URL/address in configuration has no port (e.g. "proxy.example.com" instead of "proxy.example.com:443") or is otherwise not parseable by net.SplitHostPort when the CONNECT tunnel is established.

Common situations: HTTPS_PROXY / proxy config set without a port; trailing whitespace or bracket mistakes in IPv6 proxy addresses; config migrated from an HTTP proxy (host only) to an HTTPS proxy that requires host:port.

Related errors

AI-assisted analysis of larksuite/cli@7fd6ef3c07 (2026-09-04). Data as JSON: /api/errors/74f0479bdec48ace. Report an issue: GitHub.