k3s-io/k3s · error

unsupported proxy scheme: %s

Error message

unsupported proxy scheme: %s

What it means

The agent's embedded load balancer builds a proxy.Dialer from the environment proxy URL: http/https go through httpdialer.New (10s connect timeout), socks5 through proxy.FromURL. Every other scheme falls into this error — only those three are implemented.

Source

Thrown at pkg/agent/loadbalancer/httpproxy.go:69

		return errors.WithMessagef(err, "failed to create proxy dialer for %s", proxyURL)
	}

	defaultDialer = dialer
	logrus.Debugf("Using proxy %s for agent connection to %s", proxyURL, serverURL)
	return nil
}

// proxyDialer creates a new proxy.Dialer that routes connections through the specified proxy.
func proxyDialer(proxyURL *url.URL, forward proxy.Dialer) (proxy.Dialer, error) {
	if proxyURL.Scheme == "http" || proxyURL.Scheme == "https" {
		// Create a new HTTP proxy dialer
		httpProxyDialer := httpdialer.New(proxyURL, httpdialer.WithConnectionTimeout(10*time.Second), httpdialer.WithDialer(forward.(*net.Dialer)))
		return httpProxyDialer, nil
	} else if proxyURL.Scheme == "socks5" {
		// For SOCKS5 proxies, use the proxy package's FromURL
		return proxy.FromURL(proxyURL, forward)
	}
	return nil, fmt.Errorf("unsupported proxy scheme: %s", proxyURL.Scheme)
}

View on GitHub (pinned to 6ba341e396)

Solutions

1. Change the proxy URL scheme to http://, https:// or socks5:// (note: socks5 resolves DNS locally)
2. Prefix bare host:port values with a scheme: http://proxy.corp:3128
3. Fix env var typos and re-export before starting the agent

Example fix

# before
export HTTPS_PROXY="socks5h://proxy.corp:1080"

# after
export HTTPS_PROXY="socks5://proxy.corp:1080"

u, err := url.Parse(os.Getenv("HTTPS_PROXY"))
if err == nil && u.Host != "" {
    switch u.Scheme {
    case "http", "https", "socks5":
    default:
        log.Fatalf("unsupported proxy scheme %q (use http, https or socks5)", u.Scheme)
    }
}

func supportedProxyScheme(raw string) bool {
    u, err := url.Parse(raw)
    return err == nil && (u.Scheme == "http" || u.Scheme == "https" || u.Scheme == "socks5")
}

When it happens

Trigger: HTTPS_PROXY/HTTP_PROXY/ALL_PROXY set to a URL whose scheme is not http, https or socks5: socks5h://, socks4://, ftp://, a typo like 'htps://', or a bare 'proxyhost:3128' that url.Parse treats as schemeless.

Common situations: Corporate environments standardizing on socks5h:// (DNS resolution through the proxy); env var typos; bare host:port values without a scheme.

Related errors

• server %s is stopping
• failed to read http config %s: %w
• nix-store not found in PATH: install nix (https://nixos.org/
• Initial server URL host is not defined for load balancer
• only https:// URLs are supported, invalid scheme:

AI-assisted analysis of k3s-io/k3s@6ba341e396 (2026-08-15). Data as JSON: /api/errors/eaca453089392cff. Report an issue: GitHub.