{"record":{"id":"0db36d41bddbe7a4","repo":"tokio-rs/tokio","slug":"could-not-resolve-to-any-address","errorCode":null,"errorMessage":"could not resolve to any address","messagePattern":"could not resolve to any address","errorType":"exception","errorClass":"io::Error","httpStatus":null,"severity":"error","filePath":"tokio/src/net/tcp/listener.rs","lineNumber":115,"sourceCode":"        ///\n        ///     # let _ = listener;\n        ///     Ok(())\n        /// }\n        /// ```\n        pub async fn bind<A: ToSocketAddrs>(addr: A) -> io::Result<TcpListener> {\n            let addrs = to_socket_addrs(addr).await?;\n\n            let mut last_err = None;\n\n            for addr in addrs {\n                match TcpListener::bind_addr(addr) {\n                    Ok(listener) => return Ok(listener),\n                    Err(e) => last_err = Some(e),\n                }\n            }\n\n            Err(last_err.unwrap_or_else(|| {\n                io::Error::new(\n                    io::ErrorKind::InvalidInput,\n                    \"could not resolve to any address\",\n                )\n            }))\n        }\n\n        fn bind_addr(addr: SocketAddr) -> io::Result<TcpListener> {\n            let listener = mio::net::TcpListener::bind(addr)?;\n            TcpListener::new(listener)\n        }\n    }\n\n    /// Accepts a new incoming connection from this listener.\n    ///\n    /// This function will yield once a new TCP connection is established. When\n    /// established, the corresponding [`TcpStream`] and the remote peer's\n    /// address will be returned.\n    ///","sourceCodeStart":97,"sourceCodeEnd":133,"githubUrl":"https://github.com/tokio-rs/tokio/blob/625954f365727668cb02d04172b34f1149637728/tokio/src/net/tcp/listener.rs#L97-L133","documentation":"TcpListener::bind resolves the address via to_socket_addrs, iterates each candidate, and on the failure path calls unwrap_or_else to build this InvalidInput error only when last_err is None — i.e. the resolved iterator was empty. If at least one address was tried, the OS-level bind error is returned instead. So this message specifically means 'DNS returned zero usable addresses.'","triggerScenarios":"Calling TcpListener::bind(addr) where addr is a hostname:port string whose resolution yields no A/AAAA records, or an empty address list. The for loop body never executes, last_err stays None, and the fallback error fires.","commonSituations":"Misspelled hostname; a service that has no DNS record (bare SRV/CNAME with no A); /etc/hosts misconfiguration; resolver returning an empty answer; passing an empty-string host that resolves to nothing on the platform.","solutions":["Pre-resolve with tokio::net::lookup_host and inspect the iterator length before binding.","Use a literal IP (127.0.0.1:port or [::]:port) instead of a hostname for listener binds — the common idiom.","Verify DNS records externally (dig/nslookup) for the hostname.","Distinguish this case from a real bind failure by checking that error.kind() == InvalidInput AND no os error code is attached."],"exampleFix":"// before\nlet l = TcpListener::bind(\"svc.example:8080\").await?;\n\n// after\nlet l = TcpListener::bind((\"0.0.0.0\", 8080)).await?;\n// or pre-resolve:\nlet mut addrs = tokio::net::lookup_host(\"svc.example:8080\").await?;\nif addrs.next().is_none() {\n    return Err(anyhow::anyhow!(\"no addresses resolved\"));\n}","handlingStrategy":"validation","validationCode":"// Pre-resolve and require a non-empty address list:\nlet addrs: Vec<_> = tokio::net::lookup_host((host.as_str(), port)).await?.collect();\nif addrs.is_empty() {\n    return Err(anyhow::anyhow!(\"{host} resolved to no addresses\"));\n}\nlet listener = TcpListener::bind(addrs[0]).await?;","typeGuard":"fn is_empty_resolution(e: &io::Error) -> bool {\n    e.kind() == io::ErrorKind::InvalidInput && e.raw_os_error().is_none()\n}","tryCatchPattern":"match TcpListener::bind(addr).await {\n    Ok(l) => Ok(l),\n    Err(e) if e.kind() == io::ErrorKind::InvalidInput && e.raw_os_error().is_none() => {\n        Err(anyhow::anyhow!(\"no addresses resolved for {addr}\"))\n    }\n    Err(e) => Err(e.into()),\n}","preventionTips":["Bind listeners to literal IPs (0.0.0.0 / 127.0.0.1) instead of hostnames.","Cache resolved addresses and log when resolution yields zero results.","Distinguish empty resolution (no raw os error) from kernel bind failures.","Validate hostnames at config load time, not at bind time."],"tags":["net","tcp","bind","dns","tokio"],"backgroundTag":null,"analyzedSha":"625954f365727668cb02d04172b34f1149637728","analyzedAt":"2026-08-11T17:46:45.378Z","contentChangedAt":"2026-08-11T17:46:45.378Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}