DEV Community

MinPin Proxy
MinPin Proxy

Posted on Fully Autonomous

Works on Wi-Fi, fails on some cellular networks: hardcoded IPv4 and the IPv6-only carriers

The report: "the app can't connect on my phone network, but it's fine on Wi-Fi". Support asks for the carrier, and the answer is one of the large mobile networks that run IPv6-only with NAT64. The app works for nearly everyone else, so the bug sits in the backlog for months.

What an IPv6-only network does

On many carriers, the phone gets only an IPv6 address. There is no IPv4 route at all. To keep the IPv4 internet reachable, the carrier runs two things:

  • DNS64: when the phone asks for a name that only has an IPv4 address (an A record), the carrier's DNS server makes up an IPv6 address for it (an AAAA record) by putting the IPv4 address inside a prefix, usually 64:ff9b::/96.
  • NAT64: traffic to that made-up address goes to a gateway that translates it to IPv4 and back.

So anything that starts from a hostname keeps working. Anything that starts from a raw IPv4 address has nothing to resolve, nothing gets translated, and the connection fails.

What breaks

  • An IPv4 literal anywhere in the app: http://203.0.113.10/api, a fallback server list, a "connectivity check" against 8.8.8.8, a config file from the backend that hands out IPs instead of names.
  • Code that checks the address family itself, such as rejecting anything that isn't AF_INET, or parsing an address into four bytes.
  • Old networking libraries, or C code, that call gethostbyname (IPv4 only) instead of getaddrinfo.
  • Third-party SDKs that do any of the above. You only find these in a capture.
  • Reachability checks against 0.0.0.0 or an IPv4 address, which report "no network" on a network that works fine.

Apple tests for this

App Review has required IPv6-only compatibility since 2016, and reviewers test on an IPv6-only network. "Cannot connect" rejections that nobody can reproduce in the office often come from this.

You can build the same network on a Mac: hold Option, open System Settings > General > Sharing, click the (i) next to Internet Sharing, and turn on Create NAT64 Network. Share the Mac's Ethernet connection over Wi-Fi, join that Wi-Fi from a test iPhone, and every IPv4 literal in the app fails the way it does for those users. (The Option key is what shows the NAT64 option. The menu layout changes between macOS versions, so search for "NAT64" if it isn't there.)

On Android there's no built-in switch. The easiest reproduction is a real SIM on one of the IPv6-only carriers, or a test Wi-Fi network with only IPv6 and DNS64/NAT64 configured on the router. Android's own CLAT (464XLAT) translates IPv4 traffic on most IPv6-only mobile networks, which hides many of these bugs on Android but not all of them, and not on Wi-Fi.

The fixes

  • Use hostnames everywhere. If a backend config hands out addresses, change it to hand out names. If you need a fixed address for some reason, give it a DNS name anyway.
  • Use the high-level APIs. URLSession and Network.framework on iOS, OkHttp or HttpURLConnection on Android. They resolve names with both families and use Happy Eyeballs to pick whichever connects first.
  • If you must connect to a literal IPv4 address, on iOS let getaddrinfo turn it into a NAT64 address: pass the IPv4 string as the host with AI_DEFAULT hints, and on an IPv6-only network you get back the synthesized IPv6 address. Then connect to whatever it returns, without checking the family.
  • Remove address-family checks. Store addresses as strings or sockaddr_storage, not as 4-byte integers.
  • Check reachability by doing the real request, not by pinging an IPv4 address.

Finding the literals

Search the code for IPv4 patterns, something like grep -rEn '\b([0-9]{1,3}\.){3}[0-9]{1,3}\b' --include=*.swift --include=*.kt --include=*.java --include=*.m --include=*.json ., and skip the version numbers it also matches. Then use every screen of the app on the NAT64 network and watch its logs. A connection to a literal fails right away with "network unreachable" or a timeout, without any DNS lookup before it, which is also how you spot the ones inside third-party SDKs. Connections to 64:ff9b:: addresses are fine: those are hostnames the network translated as intended.


This article was created with the help of AI.

Top comments (0)