What causes "Failed to lookup the host" in rathole-org/rathole?

Verify the hostname is correct and resolvable: `nslookup ` / `dig `

Failed to lookup the host

Error message

Failed to lookup the host

What it means

`to_socket_addr` resolves a host via `lookup_host` and takes the first result; this error is returned when resolution yields no addresses (or the underlying lookup fails). It means the given hostname/port could not be turned into a `SocketAddr` at that moment.

Solutions

Verify the hostname is correct and resolvable: `nslookup <host>` / `dig <host>`
Use an IP address instead of a hostname to bypass DNS
Check network connectivity and DNS server configuration (resolv.conf, VPN, firewall)
Retry — transient DNS failures resolve themselves; consider a fallback address

Example fix

// before
let addr = to_socket_addr("my-host.example:8080").await?;

// after
let addr = to_socket_addr("203.0.113.10:8080").await?; // or fixed hostname + retry

Defensive patterns

Strategy: retry

Validate before calling

// pre-check reachability of the host before calling the API
if host.parse::<std::net::IpAddr>().is_err()
    && std::net::ToSocketAddrs::to_socket_addrs(&(host.as_str(), port))
        .map(|mut i| i.next().is_some())
        .unwrap_or(false)
{
    // resolvable, safe to proceed
}

Try / catch

match to_socket_addr(&addr).await {
    Ok(a) => a,
    Err(e) if e.to_string().contains("Failed to lookup") => {
        tokio::time::sleep(Duration::from_secs(2)).await;
        to_socket_addr(&addr).await? // retry once, then fall back to IP
    }
    Err(e) => return Err(e),
}

Prevention

Prefer stable hostnames or IPs in configs; pin DNS via /etc/hosts for critical nodes
Add retry-with-backoff around DNS resolution for transient failures
Monitor DNS health; use a reliable resolver
Validate hostnames resolve before startup and fail fast with a clear message

When it happens

Trigger: Calling `to_socket_addr` (directly or via `udp_connect`/`resolve`) with a hostname whose DNS lookup returns no records, an unresolvable hostname, DNS server failure, no network, or an unparsable address string propagated through `ToSocketAddrs`.

Common situations: Typoed `remote_addr`/`bind_addr` hostnames in config; DNS outage or offline environment; /etc/hosts or resolver misconfiguration; resolving a name that only has AAAA/only A records when the family is filtered.

Related errors

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

Appendix: source

Thrown at src/helper.rs:58

    panic!(
        "The feature '{}' is not compiled in this binary. Please re-compile rathole",
        feature
    )
}

#[allow(dead_code)]
pub fn feature_neither_compile(feature1: &str, feature2: &str) -> ! {
    panic!(
        "Neither of the feature '{}' or '{}' is compiled in this binary. Please re-compile rathole",
        feature1, feature2
    )
}

pub async fn to_socket_addr<A: ToSocketAddrs>(addr: A) -> Result<SocketAddr> {
    lookup_host(addr)
        .await?
        .next()
        .ok_or_else(|| anyhow!("Failed to lookup the host"))
}

pub fn host_port_pair(s: &str) -> Result<(&str, u16)> {
    let semi = s.rfind(':').expect("missing semicolon");
    Ok((&s[..semi], s[semi + 1..].parse()?))
}

/// Create a UDP socket and connect to `addr`
pub async fn udp_connect<A: ToSocketAddrs>(addr: A, prefer_ipv6: bool) -> Result<UdpSocket> {

    let (socket_addr, bind_addr);

    match prefer_ipv6 {
        false => {
            socket_addr = to_socket_addr(addr).await?;

            bind_addr = match socket_addr {
                SocketAddr::V4(_) => "0.0.0.0:0",

View on GitHub (pinned to a292f7ed54)