{"record":{"id":"96025d4ac076c805","repo":"rathole-org/rathole","slug":"failed-to-lookup-the-host","errorCode":null,"errorMessage":"Failed to lookup the host","messagePattern":"Failed to lookup the host","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/helper.rs","lineNumber":58,"sourceCode":"    panic!(\n        \"The feature '{}' is not compiled in this binary. Please re-compile rathole\",\n        feature\n    )\n}\n\n#[allow(dead_code)]\npub fn feature_neither_compile(feature1: &str, feature2: &str) -> ! {\n    panic!(\n        \"Neither of the feature '{}' or '{}' is compiled in this binary. Please re-compile rathole\",\n        feature1, feature2\n    )\n}\n\npub async fn to_socket_addr<A: ToSocketAddrs>(addr: A) -> Result<SocketAddr> {\n    lookup_host(addr)\n        .await?\n        .next()\n        .ok_or_else(|| anyhow!(\"Failed to lookup the host\"))\n}\n\npub fn host_port_pair(s: &str) -> Result<(&str, u16)> {\n    let semi = s.rfind(':').expect(\"missing semicolon\");\n    Ok((&s[..semi], s[semi + 1..].parse()?))\n}\n\n/// Create a UDP socket and connect to `addr`\npub async fn udp_connect<A: ToSocketAddrs>(addr: A, prefer_ipv6: bool) -> Result<UdpSocket> {\n\n    let (socket_addr, bind_addr);\n\n    match prefer_ipv6 {\n        false => {\n            socket_addr = to_socket_addr(addr).await?;\n\n            bind_addr = match socket_addr {\n                SocketAddr::V4(_) => \"0.0.0.0:0\",","sourceCodeStart":40,"sourceCodeEnd":76,"githubUrl":"https://github.com/rathole-org/rathole/blob/a292f7ed5402f840415fc6a53827da2f34337856/src/helper.rs#L40-L76","documentation":"`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.","triggerScenarios":"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`.","commonSituations":"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.","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"],"exampleFix":"// before\nlet addr = to_socket_addr(\"my-host.example:8080\").await?;\n\n// after\nlet addr = to_socket_addr(\"203.0.113.10:8080\").await?; // or fixed hostname + retry","handlingStrategy":"retry","validationCode":"// pre-check reachability of the host before calling the API\nif host.parse::<std::net::IpAddr>().is_err()\n    && std::net::ToSocketAddrs::to_socket_addrs(&(host.as_str(), port))\n        .map(|mut i| i.next().is_some())\n        .unwrap_or(false)\n{\n    // resolvable, safe to proceed\n}","typeGuard":null,"tryCatchPattern":"match to_socket_addr(&addr).await {\n    Ok(a) => a,\n    Err(e) if e.to_string().contains(\"Failed to lookup\") => {\n        tokio::time::sleep(Duration::from_secs(2)).await;\n        to_socket_addr(&addr).await? // retry once, then fall back to IP\n    }\n    Err(e) => return Err(e),\n}","preventionTips":["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"],"tags":["network","dns","rust"],"backgroundTag":"dns-resolution-failed","analyzedSha":"a292f7ed5402f840415fc6a53827da2f34337856","analyzedAt":"2026-09-07T09:56:55.739Z","contentChangedAt":"2026-09-07T09:56:55.739Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}