Network.framework Diagnostics
Overview
Core principle 85% of networking problems stem from misunderstanding connection states, not handling network transitions, or improper error handling—not Network.framework defects.
Network.framework is battle-tested in every iOS app (powers URLSession internally), handles trillions of requests daily, and provides smart connection establishment with Happy Eyeballs, proxy evaluation, and WiFi Assist. If your connection is failing, timing out, or behaving unexpectedly, the issue is almost always in how you're using the framework, not the framework itself.
This skill provides systematic diagnostics to identify root causes in minutes, not hours.
Red Flags — Suspect Networking Issue
If you see ANY of these, suspect a networking misconfiguration, not framework breakage:
-
Connection times out after 60 seconds with no clear error
-
TLS handshake fails with "certificate invalid" on some networks
-
Data sent but never arrives at receiver
-
Connection drops when switching WiFi to cellular
-
Works perfectly on WiFi but fails 100% of time on cellular
-
Works in simulator but fails on real device
-
Connection succeeds on your network but fails for users
-
❌ FORBIDDEN "Network.framework is broken, we should rewrite with sockets"
- Network.framework powers URLSession, used in every iOS app
- Handles edge cases you'll spend months discovering with sockets
- Apple engineers have 10+ years of production debugging baked into framework
- Switching to sockets will expose you to 100+ edge cases
Critical distinction Simulator uses macOS networking stack (not iOS), hides cellular-specific issues (IPv6-only networks), and doesn't simulate network transitions. MANDATORY: Test on real device with real network conditions.
Mandatory First Steps
ALWAYS run these commands FIRST (before changing code):
connection.stateUpdateHandler = { state in
print("\(Date()): Connection state: \(state)")
}
print("TLS version: \(tlsParameters.minimumTLSProtocolVersion)")
print("Cipher suites: \(tlsParameters.tlsCipherSuites ?? [])")
What this tells you
| Observation |
Diagnosis |
Next Step |
| Stuck in .preparing > 5 seconds |
DNS failure or network down |
Pattern 1a |
| Moves to .waiting immediately |
No connectivity (Airplane Mode, no signal) |
Pattern 1b |
| .failed with POSIX error 61 |
Connection refused (server not listening) |
Pattern 1c |
| .failed with POSIX error 50 |
Network down (interface disabled) |
Pattern 1d |
| .ready then immediate .failed |
TLS handshake failure |
Pattern 2b |
| .ready, send succeeds, no data arrives |
Framing problem or receiver not processing |
Pattern 3a |
| Works WiFi, fails cellular |
IPv6-only network (hardcoded IPv4) |
Pattern 5a |
| Works without VPN, fails with VPN |
Proxy interference or DNS override |
Pattern 5b |
MANDATORY INTERPRETATION
Before changing ANY code, identify ONE of these:
- If stuck in .preparing AND network is available → DNS failure (check nslookup)
- If .waiting immediately AND Airplane Mode is off → Interface-specific issue (cellular blocked)
- If .failed POSIX 61 → Server issue (check server logs)
- If .failed with TLS error -9806 → Certificate validation (check with openssl)
- If .ready but data not arriving → Framing or receiver issue (enable packet capture)
If diagnostics are contradictory or unclear
- STOP. Do NOT proceed to patterns yet
- Add timestamp logging to every send/receive call
- Enable packet capture (Charles/Wireshark)
- Test on different device to isolate hardware vs software issue
Decision Tree
Use this to reach the correct diagnostic pattern in 2 minutes:
Network problem?
├─ Connection never reaches .ready?
│ ├─ Stuck in .preparing for >5 seconds?
│ │ ├─ DNS lookup timing out? → Pattern 1a (DNS Failure)
│ │ ├─ Network available but can't reach host? → Pattern 1c (Connection Refused)
│ │ └─ First connection slow, subsequent fast? → Pattern 1e (DNS Caching)
│ │
│ ├─ Moves to .waiting immediately?
│ │ ├─ Airplane Mode or no signal? → Pattern 1b (No Connectivity)
│ │ ├─ Cellular blocked by parameters? → Pattern 1b (Interface Restrictions)
│ │ └─ VPN connecting? → Wait and retry
│ │
│ ├─ .failed with POSIX error 61?
│ │ └─ → Pattern 1c (Connection Refused)
│ │
│ └─ .failed with POSIX error 50?
│ └─ → Pattern 1d (Network Down)
│
├─ Connection reaches .ready, then fails?
│ ├─ Fails immediately after .ready?
│ │ ├─ TLS error -9806? → Pattern 2b (Certificate Validation)
│ │ ├─ TLS error -9801? → Pattern 2b (Protocol Version)
│ │ └─ POSIX error 54? → Pattern 2d (Connection Reset)
│ │
│ ├─ Fails after network change (WiFi → cellular)?
│ │ ├─ No viabilityUpdateHandler? → Pattern 2a (Viability Not Handled)
│ │ ├─ Didn't detect better path? → Pattern 2a (Better Path)
│ │ └─ IPv6 → IPv4 transition? → Pattern 5a (Dual Stack)
│ │
│ ├─ Fails after timeout?
│ │ └─ → Pattern 2c (Receiver Not Responding)
│ │
│ └─ Random disconnects?
│ └─ → Pattern 2d (Network Instability)
│
├─ Data not arriving?
│ ├─ Send succeeds, receive never returns?
│ │ ├─ No message framing? → Pattern 3a (Framing Problem)
│ │ ├─ Wrong byte count? → Pattern 3b (Min/Max Bytes)
│ │ └─ Receiver not calling receive()? → Check receiver code
│ │
│ ├─ Partial data arrives?
│ │ ├─ receive(exactly:) too large? → Pattern 3b (Chunking)
│ │ ├─ Sender closing too early? → Check sender lifecycle
│ │ └─ Buffer overflow? → Pattern 3b (Buffer Management)
│ │
│ ├─ Data corrupted?
│ │ ├─ TLS disabled? → Pattern 3c (No Encryption)
│ │ ├─ Binary vs text encoding? → Check ContentType
│ │ └─ Byte order (endianness)? → Use network byte order
│ │
│ └─ Works sometimes, fails intermittently?
│ └─ → Pattern 3d (Race Condition)
│
├─ Performance degrading?
│ ├─ Latency increasing over time?
│ │ ├─ TCP congestion? → Pattern 4a (Congestion Control)
│ │ ├─ No contentProcessed pacing? → Pattern 4a (Buffering)
│ │ └─ Server overloaded? → Check server metrics
│ │
│ ├─ Throughput decreasing?
│ │ ├─ Network transition WiFi → cellular? → Pattern 4b (Bandwidth Change)
│ │ ├─ Packet loss increasing? → Pattern 4b (Network Quality)
│ │ └─ Multiple streams competing? → Pattern 4b (Prioritization)
│ │
│ ├─ High CPU usage?
│ │ ├─ Not using batch for UDP? → Pattern 4c (Batching)
│ │ ├─ Too many small sends? → Pattern 4c (Coalescing)
│ │ └─ Using sockets instead of Network.framework? → Migrate (30% CPU savings)
│ │
│ └─ Memory growing?
│ ├─ Not releasing connections? → Pattern 4d (Connection Leaks)
│ ├─ Not cancelling on deinit? → Pattern 4d (Lifecycle)
│ └─ Missing [weak self]? → Pattern 4d (Retain Cycles)
│
└─ Works on WiFi, fails on cellular/VPN?
├─ IPv6-only cellular network?
│ ├─ Hardcoded IPv4 address? → Pattern 5a (IPv4 Literal)
│ ├─ getaddrinfo with AF_INET only? → Pattern 5a (Address Family)
│ └─ Works on some carriers, not others? → Pattern 5a (Regional IPv6)
│
├─ Corporate VPN active?
│ ├─ Proxy configuration failing? → Pattern 5b (PAC)
│ ├─ DNS override blocking hostname? → Pattern 5b (DNS)
│ └─ Certificate pinning failing? → Pattern 5b (TLS in VPN)
│
├─ Port blocked by firewall?
│ ├─ Non-standard port? → Pattern 5c (Firewall)
│ ├─ Outbound only? → Pattern 5c (NATing)
│ └─ Works on port 443, not 8080? → Pattern 5c (Port Scanning)
│
├─ Peer-to-peer connection failing?
│ ├─ NAT traversal issue? → Pattern 5d (STUN/TURN)
│ ├─ Symmetric NAT? → Pattern 5d (NAT Type)
│ └─ Local network only? → Pattern 5d (Bonjour/mDNS)
│
└─ URLSession fails but NWConnection works?
├─ HTTP URL blocked? → Pattern 6a (ATS HTTP Block)
├─ "SSL error" on HTTPS? → Pattern 6b (ATS TLS Version)
└─ Works on older iOS? → Pattern 6a/6b (ATS enforcement)
Pattern Selection Rules (MANDATORY)
Before proceeding to a pattern:
- Connection never reaching .ready → Start with Pattern 1 (DNS, connectivity, refused)
- TLS error codes → Jump directly to Pattern 2b (Certificate validation)
- Data not arriving → Enable packet capture FIRST, then Pattern 3
- Network-specific (works WiFi, fails cellular) → Test on that exact network, Pattern 5
- Performance degradation → Profile with Instruments Network template, Pattern 4
Apply ONE pattern at a time
- Implement the fix from one pattern
- Test thoroughly
- Only if issue persists, try next pattern
- DO NOT apply multiple patterns simultaneously (can't isolate cause)
FORBIDDEN
- Guessing at solutions without diagnostics
- Changing multiple things at once
- Assuming "just needs more timeout"
- Disabling TLS "temporarily"
- Switching to sockets to "avoid framework issues"
Diagnostic Patterns
Pattern 1a: DNS Resolution Failure
Time cost 10-15 minutes
Symptom
- Connection stuck in .preparing for >5 seconds
- Eventually fails or times out
- Works with IP address but not hostname
- Works on one network, fails on another
Diagnosis
Common causes
- DNS server unreachable (corporate network blocks external DNS)
- Hostname typo or doesn't exist
- DNS caching stale entry (rare, but happens)
- VPN blocking DNS resolution
Fix
let connection = NWConnection(
host: NWEndpoint.Host("correct-hostname.com"),
port: 443,
using: .tls
)
Verification
- Run
nslookup your-hostname.com — should return IP in <1 second
- Test on cellular (different DNS servers) — should work
- Check corporate network DNS configuration
Prevention
- Use well-known hostnames (don't rely on internal DNS)
- Test on multiple networks during development
- Don't hardcode IPs (if DNS fails, you need to fix DNS, not bypass it)
Pattern 2b: TLS Certificate Validation Failure
Time cost 15-20 minutes
Symptom
- Connection reaches .ready briefly, then .failed immediately
- Error:
-9806 (kSSLPeerCertInvalid)
- Error:
-9807 (kSSLPeerCertExpired)
- Error:
-9801 (kSSLProtocol)
- Works on some servers, fails on others
Diagnosis
openssl s_client -connect example.com:443 -showcerts
openssl s_client -connect example.com:443 | openssl x509 -noout -dates
openssl s_client -connect example.com:443 -showcerts | grep "CN="
Common causes
- Self-signed certificate (dev/staging servers)
- Expired certificate
- Certificate hostname mismatch (cert for "example.com" but connecting to "www.example
