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):

// 1. Enable Network.framework logging
// Add to Xcode scheme: Product → Scheme → Edit Scheme → Arguments
// -NWLoggingEnabled 1
// -NWConnectionLoggingEnabled 1

// 2. Check connection state history
connection.stateUpdateHandler = { state in
    print("\(Date()): Connection state: \(state)")
    // Log every state transition with timestamp
}

// 3. Check TLS configuration
// If using custom TLS parameters:
print("TLS version: \(tlsParameters.minimumTLSProtocolVersion)")
print("Cipher suites: \(tlsParameters.tlsCipherSuites ?? [])")

// 4. Test with packet capture (Charles Proxy or Wireshark)
// On device: Settings → WiFi → (i) → Configure Proxy → Manual
// Charles: Help → SSL Proxying → Install Charles Root Certificate on iOS

// 5. Test on different networks
// - WiFi
// - Cellular (disable WiFi)
// - Airplane Mode → WiFi (test waiting state)
// - VPN active
// - IPv6-only (some cellular carriers)

What this tells you

MANDATORY INTERPRETATION

Before changing ANY code, identify ONE of these:

1. If stuck in .preparing AND network is available → DNS failure (check nslookup)
2. If .waiting immediately AND Airplane Mode is off → Interface-specific issue (cellular blocked)
3. If .failed POSIX 61 → Server issue (check server logs)
4. If .failed with TLS error -9806 → Certificate validation (check with openssl)
5. 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:

1. Connection never reaching .ready → Start with Pattern 1 (DNS, connectivity, refused)
2. TLS error codes → Jump directly to Pattern 2b (Certificate validation)
3. Data not arriving → Enable packet capture FIRST, then Pattern 3
4. Network-specific (works WiFi, fails cellular) → Test on that exact network, Pattern 5
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

// Enable DNS logging
// -NWLoggingEnabled 1

// Check DNS resolution manually
// Terminal: nslookup example.com
// Terminal: dig example.com

// Logs show:
// "DNS lookup timed out"
// "getaddrinfo failed: 8 (nodename nor servname provided)"

Common causes

1. DNS server unreachable (corporate network blocks external DNS)
2. Hostname typo or doesn't exist
3. DNS caching stale entry (rare, but happens)
4. VPN blocking DNS resolution

Fix

// ❌ WRONG — Adding timeout doesn't fix DNS
/*
let parameters = NWParameters.tls
parameters.expiredDNSBehavior = .allow // Doesn't help if DNS never resolves
*/

// ✅ CORRECT — Verify hostname, test DNS manually
// 1. Test DNS manually:
// $ nslookup your-hostname.com
// If this fails, DNS is the problem (not your code)

// 2. If DNS works manually but not in app:
// Check if VPN or enterprise config blocking app DNS

// 3. If hostname doesn't exist:
let connection = NWConnection(
    host: NWEndpoint.Host("correct-hostname.com"), // Fix typo
    port: 443,
    using: .tls
)

// 4. If DNS caching issue (rare):
// Restart device to clear DNS cache
// Or use IP address temporarily while investigating DNS server issue

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

# Test TLS manually with openssl
openssl s_client -connect example.com:443 -showcerts

# Check certificate details
openssl s_client -connect example.com:443 | openssl x509 -noout -dates
# notBefore: Jan  1 00:00:00 2024 GMT
# notAfter: Dec 31 23:59:59 2024 GMT ← Check if expired

# Check certificate chain
openssl s_client -connect example.com:443 -showcerts | grep "CN="
# Should show: Subject CN=example.com, Issuer CN=Trusted CA

Common causes

1. Self-signed certificate (dev/staging servers)
2. Expired certificate
3. Certificate hostname mismatch (cert for "example.com" but connecting to "www.example