{"record":{"id":"a14b15451444ea34","repo":"shadowsocks/shadowsocks-rust","slug":"invalid-ipv6-address","errorCode":null,"errorMessage":"Invalid IPv6 address","messagePattern":"Invalid IPv6 address","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/shadowsocks/src/net/sys/unix/bsd/freebsd.rs","lineNumber":236,"sourceCode":"                    return Err(io::Error::last_os_error());\n                }\n            }\n        }\n    }\n\n    Ok(())\n}\n\n/// Create a `UdpSocket` with specific address family\n#[inline]\npub async fn create_outbound_udp_socket(af: AddrFamily, config: &ConnectOpts) -> io::Result<UdpSocket> {\n    let bind_addr = match (af, config.bind_local_addr) {\n        (AddrFamily::Ipv4, Some(SocketAddr::V4(addr))) => addr.into(),\n        (AddrFamily::Ipv4, Some(SocketAddr::V6(addr))) => {\n            // Map IPv6 bind_local_addr to IPv4 if AF is IPv4\n            match addr.ip().to_ipv4_mapped() {\n                Some(addr) => SocketAddr::new(addr.into(), 0),\n                None => return Err(io::Error::new(ErrorKind::InvalidInput, \"Invalid IPv6 address\")),\n            }\n        }\n        (AddrFamily::Ipv6, Some(SocketAddr::V6(addr))) => addr.into(),\n        (AddrFamily::Ipv6, Some(SocketAddr::V4(addr))) => {\n            // Map IPv4 bind_local_addr to IPv6 if AF is IPv6\n            SocketAddr::new(addr.ip().to_ipv6_mapped().into(), 0)\n        }\n        (AddrFamily::Ipv4, ..) => SocketAddr::new(Ipv4Addr::UNSPECIFIED.into(), 0),\n        (AddrFamily::Ipv6, ..) => SocketAddr::new(Ipv6Addr::UNSPECIFIED.into(), 0),\n    };\n\n    bind_outbound_udp_socket(&bind_addr, config).await\n}\n\n/// Create a `UdpSocket` binded to `bind_addr`\npub async fn bind_outbound_udp_socket(bind_addr: &SocketAddr, config: &ConnectOpts) -> io::Result<UdpSocket> {\n    let af = AddrFamily::from(bind_addr);\n","sourceCodeStart":218,"sourceCodeEnd":254,"githubUrl":"https://github.com/shadowsocks/shadowsocks-rust/blob/8eb0f0a65b1d976ab6bed5787327ef86529b0435/crates/shadowsocks/src/net/sys/unix/bsd/freebsd.rs#L218-L254","documentation":"create_outbound_udp_socket on FreeBSD binds to config.bind_local_addr when present. If the socket address family is IPv4 but bind_local_addr is IPv6, the code converts it via to_ipv4_mapped(); an IPv6 address that is not of the ::ffff:a.b.c.d form cannot be mapped, so the call returns ErrorKind::InvalidInput with this message.","triggerScenarios":"Calling create_outbound_udp_socket with AddrFamily::Ipv4 while ServerConfig.bind_local_addr is Some(SocketAddr::V6(addr)) whose IP is not an IPv4-mapped IPv6 address.","commonSituations":"Setting bind_local_addr to a real IPv6 address (e.g. :: or 2001:db8::1) while connecting to an IPv4 server; config copied between IPv4/IPv6 deployments.","solutions":["Use an IPv4 bind_local_addr when the outbound address family is IPv4","Use an IPv4-mapped IPv6 literal (e.g. ::ffff:192.168.1.1) if IPv6 notation is required","Clear bind_local_addr to let the OS choose the source address","Check the destination family in code and select a matching bind address"],"exampleFix":"// before\nlet config = ServerConfig::new(addr).set_bind_local_addr(\"2001:db8::1:1080\".parse().unwrap());\n// after\nlet config = ServerConfig::new(addr).set_bind_local_addr(\"0.0.0.0:1080\".parse().unwrap());","handlingStrategy":"validation","validationCode":"if let Some(SocketAddr::V6(v6)) = config.bind_local_addr {\n    if af == AddrFamily::Ipv4 && v6.ip().to_ipv4_mapped().is_none() {\n        bail!(\"bind_local_addr not mappable to IPv4\");\n    }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Set an IPv4 bind_local_addr for IPv4 outbound sockets","Clear bind_local_addr when unsure; OS picks a valid source","Test configs on both IPv4 and IPv6 endpoints"],"tags":["ipv6","udp","freebsd","bind"],"backgroundTag":"invalid-config-value","analyzedSha":"8eb0f0a65b1d976ab6bed5787327ef86529b0435","analyzedAt":"2026-09-09T12:20:43.168Z","contentChangedAt":"2026-09-09T12:20:43.168Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}