What causes "Unknown proxy scheme: {}" in rathole-org/rathole?

Change the proxy URL scheme to `socks5://` or `http://`

Unknown proxy scheme

Error message

Unknown proxy scheme: {}

What it means

When `[transport]`/`[network].tcp.proxy` is set, `validate_transport_config` checks the proxy URL scheme and only accepts `socks5` or `http`. Any other scheme (or a URL whose scheme can't be recognized) is rejected with this error at config-validation time.

Solutions

Change the proxy URL scheme to `socks5://` or `http://`
If it's a SOCKS proxy with remote DNS (`socks5h`), use `socks5://` — DNS resolution behavior is handled by the library
Add the scheme to a bare proxy address, e.g. `proxy = "socks5://127.0.0.1:1080"`
If you need an unsupported scheme (socks4/https), put a local protocol-converting proxy in front or use a supported proxy

Example fix

# before
proxy = "socks5h://127.0.0.1:1080"

# after
proxy = "socks5://127.0.0.1:1080"

Defensive patterns

Strategy: validation

Validate before calling

let u: url::Url = proxy.parse()?;
match u.scheme() {
    "socks5" | "http" => Ok(()),
    s => Err(format!("unsupported proxy scheme: {}", s)),
}?;

Prevention

Only use socks5:// or http:// proxy URLs
Never write a bare host:port as the proxy value — always include the scheme
Check the release docs before assuming socks5h/https proxies are supported

When it happens

Trigger: Setting `proxy = "..."` under the tcp transport's network options with a scheme other than `socks5:` or `http:`, e.g. `https://...`, `socks5h://...`, `socks4://...`, or a URL missing a scheme such as `proxy = "127.0.0.1:1080"`.

Common situations: Users copy a `socks5h://` URL from curl or a browser proxy setting; they omit the scheme and give a bare host:port; they assume HTTPS proxies are supported.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

AI-assisted analysis of rathole-org/rathole@a292f7ed54 (2026-09-07). Data as JSON: /api/errors/ece413567916c906. Report an issue: GitHub.

Appendix: source

Thrown at src/config.rs:303

            if s.retry_interval.is_none() {
                s.retry_interval = Some(client.retry_interval);
            }
        }

        Config::validate_transport_config(&client.transport, false)?;

        Ok(())
    }

    fn validate_transport_config(config: &TransportConfig, is_server: bool) -> Result<()> {
        config
            .tcp
            .proxy
            .as_ref()
            .map_or(Ok(()), |u| match u.scheme() {
                "socks5" => Ok(()),
                "http" => Ok(()),
                _ => Err(anyhow!(format!("Unknown proxy scheme: {}", u.scheme()))),
            })?;
        match config.transport_type {
            TransportType::Tcp => Ok(()),
            TransportType::Tls => {
                let tls_config = config
                    .tls
                    .as_ref()
                    .ok_or_else(|| anyhow!("Missing TLS configuration"))?;
                if is_server {
                    tls_config
                        .pkcs12
                        .as_ref()
                        .and(tls_config.pkcs12_password.as_ref())
                        .ok_or_else(|| anyhow!("Missing `pkcs12` or `pkcs12_password`"))?;
                }
                Ok(())
            }
            TransportType::Noise => {

View on GitHub (pinned to a292f7ed54)