Mac Network Troubleshooting: A Developer's Checklist

Network issues are among the most frustrating problems developers face. Whether you're trying to connect to a local development server, debugging API calls, or troubleshooting DNS resolution, having a systematic approach to network troubleshooting saves time and reduces stress.

This comprehensive checklist covers essential network troubleshooting techniques for Mac developers, from basic connectivity tests to advanced DNS debugging.

The troubleshooting mindset

Before diving into specific commands, adopt a systematic approach:

1. Start simple: Test basic connectivity before diving deep 2. Isolate the problem: Is it your Mac, your network, or the remote server? 3. Check recent changes: Did you modify hosts file, network settings, or install new software? 4. Document findings: Keep notes of what works and what doesn't 5. Test incrementally: Make one change at a time

Basic connectivity tests

Ping: The first diagnostic tool

ping is your starting point for any network troubleshooting. It tests basic connectivity to a host.

Basic usage:

ping example.com

What to look for:

• Response times: Lower is better (typically <50ms for local, <200ms for internet)
• Packet loss: Should be 0%
• Consistent responses: Large variations indicate network issues

Advanced ping options:

# Send specific number of packets
ping -c 10 example.com

# Set interval between packets (seconds)
ping -i 2 example.com

# Specify packet size
ping -s 1000 example.com

# Ping IPv6 address
ping6 ::1

Common ping results:

Success:

PING example.com (93.184.216.34): 56 data bytes
64 bytes from 93.184.216.34: icmp_seq=0 ttl=54 time=25.123 ms
64 bytes from 93.184.216.34: icmp_seq=1 ttl=54 time=24.987 ms

Failure:

ping: cannot resolve example.com: Unknown host
# OR
Request timeout for icmp_seq 0

When ping fails:

• DNS resolution problem (check hosts file, DNS servers)
• Firewall blocking ICMP
• Network connectivity issue
• Host is down

Testing localhost connectivity

Always verify localhost works first:

# IPv4 localhost
ping 127.0.0.1

# IPv6 localhost
ping6 ::1

# Hostname localhost
ping localhost

If localhost fails, you have a serious system issue, not a network problem.

DNS troubleshooting

DNS issues are common in development environments. Here's how to diagnose them systematically.

Check your hosts file

The hosts file is checked before DNS, so verify it first:

# View hosts file
cat /etc/hosts

# Search for specific domain
grep "example.com" /etc/hosts

# Check if file is readable
ls -l /etc/hosts

Common hosts file issues:

• Syntax errors (missing spaces, invalid IPs)
• Duplicate entries (first one wins)
• Wrong IP address
• Comments interfering (unlikely but possible)

Test DNS resolution

Using nslookup:

# Basic lookup
nslookup example.com

# Query specific DNS server
nslookup example.com 8.8.8.8

# Interactive mode (type 'exit' to quit)
nslookup
> example.com
> server 8.8.8.8
> example.com

Using dig (more detailed):

# Basic lookup
dig example.com

# Query specific DNS server
dig @8.8.8.8 example.com

# Get only the answer section
dig +short example.com

# Reverse DNS lookup (IP to domain)
dig -x 93.184.216.34

# Query specific record type
dig example.com MX    # Mail records
dig example.com TXT   # Text records
dig example.com AAAA  # IPv6 records

Using host command:

# Basic lookup
host example.com

# Verbose output
host -v example.com

# Reverse lookup
host 93.184.216.34

Check DNS servers

View current DNS servers:

# Using scutil
scutil --dns | grep nameserver

# Using networksetup
networksetup -getdnsservers Wi-Fi
networksetup -getdnsservers Ethernet

# All DNS info
scutil --dns

Test DNS server response:

# Test if DNS server is reachable
ping 8.8.8.8

# Test DNS resolution with specific server
dig @8.8.8.8 example.com

# Compare response times
time dig @8.8.8.8 example.com
time dig @1.1.1.1 example.com

Flush DNS cache

After modifying hosts file or when DNS changes aren't taking effect:

# Flush DNS cache (macOS)
sudo dscacheutil -flushcache
sudo killall -HUP mDNSResponder

# Verify cache is cleared
sudo killall -INFO mDNSResponder

When to flush DNS:

• After editing hosts file
• After DNS record changes
• When seeing stale DNS results
• After network configuration changes

Advanced network diagnostics

Traceroute: Mapping the network path

traceroute shows the path packets take from your Mac to a destination:

# Basic traceroute
traceroute example.com

# Specify number of hops
traceroute -m 20 example.com

# Use specific protocol
traceroute -I example.com    # ICMP
traceroute -T example.com     # TCP

Reading traceroute output:

traceroute to example.com (93.184.216.34), 64 hops max
 1  router.local (192.168.1.1)  2.123 ms  1.987 ms  2.045 ms
 2  10.0.0.1 (10.0.0.1)  15.234 ms  14.987 ms  15.123 ms
 3  * * *
 4  example.com (93.184.216.34)  25.123 ms  24.987 ms  25.045 ms

• Hop numbers: Each router/gateway along the path
• Response times: Three measurements per hop
• **Asterisks (*)**: Timeout or firewall blocking

What to look for:

• High latency at specific hop: Problem at that network point
• **Timeouts (*)**: Firewall or network issue
• Sudden latency increase: Congestion or routing problem

Testing specific ports

Using nc (netcat):

# Test if port is open
nc -zv example.com 80
nc -zv example.com 443

# Test with timeout
nc -zv -w 5 example.com 8080

# Verbose output
nc -zv example.com 22

Using telnet:

# Test port connectivity
telnet example.com 80

# If connection succeeds, you'll see connection message
# Press Ctrl+] then type 'quit' to exit

Using curl for HTTP/HTTPS:

# Test HTTP endpoint
curl -v http://example.com

# Test HTTPS endpoint
curl -v https://example.com

# Test with specific timeout
curl --connect-timeout 10 https://example.com

# Test specific port
curl http://example.com:8080

Network interface information

View network interfaces:

# List all interfaces
ifconfig

# Specific interface
ifconfig en0
ifconfig en1

# Brief summary
ifconfig | grep "inet "

# IPv6 addresses
ifconfig | grep "inet6 "

View routing table:

# Show routing table
netstat -rn

# Find route to specific host
route get example.com

Check network statistics:

# Network statistics
netstat -i

# Active connections
netstat -an

# Show process using network
lsof -i

# Connections for specific port
lsof -i :8080

macOS Network Preferences

Accessing network settings

Via System Settings (macOS Ventura+): 1. System Settings > Network 2. Select your connection (Wi-Fi/Ethernet) 3. Click "Details" for advanced options

Via System Preferences (macOS Monterey and earlier): 1. System Preferences > Network 2. Select connection from sidebar 3. Click "Advanced" for detailed settings

Key settings to check

DNS servers:

• Verify DNS servers are correct and reachable
• Add backup DNS servers (8.8.8.8, 1.1.1.1)
• Remove incorrect or unreachable servers

IPv4/IPv6 configuration:

• Most networks use DHCP (automatic)
• Verify you're getting an IP address
• Check subnet mask and router address

Proxy settings:

• Ensure proxy isn't interfering
• Check if corporate proxy is blocking connections
• Verify proxy credentials if required

Firewall:

• System Settings > Network > Firewall
• Check if firewall is blocking connections
• Review firewall rules and exceptions

Network service order:

• System Settings > Network > (gear icon) > Set Service Order
• Ensure primary connection is first
• Prevents Mac from using wrong network

Command-line network configuration

Change DNS servers:

# Set DNS for Wi-Fi
sudo networksetup -setdnsservers Wi-Fi 8.8.8.8 8.8.4.4

# Set DNS for Ethernet
sudo networksetup -setdnsservers Ethernet 1.1.1.1 1.0.0.1

# Add DNS server (append)
sudo networksetup -setdnsservers Wi-Fi "Empty"
sudo networksetup -setdnsservers Wi-Fi 8.8.8.8

# Remove DNS servers (use "Empty")
sudo networksetup -setdnsservers Wi-Fi "Empty"

Renew DHCP lease:

# Release and renew IP address
sudo ipconfig set en0 DHCP

# Or via networksetup
sudo networksetup -setdhcp Wi-Fi

Restart network interface:

# Turn Wi-Fi off and on
networksetup -setairportpower en0 off
networksetup -setairportpower en0 on

# Restart specific interface
sudo ifconfig en0 down
sudo ifconfig en0 up

Firewall troubleshooting

Check firewall status

# Check if firewall is enabled
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate

# List firewall rules
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --listapps

# Get firewall logging
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --getloggingmode

Temporarily disable firewall for testing

Via System Settings: 1. System Settings > Network > Firewall 2. Turn firewall off temporarily 3. Test your connection 4. Re-enable firewall

Important: Only disable firewall for testing. Re-enable it immediately after.

Common development scenarios

Local development server not accessible

Symptoms:

• Can't connect to localhost:3000
• Connection refused errors
• Timeout errors

Checklist: 1. Verify server is running: ps aux | grep node (or your server process) 2. Check if port is in use: lsof -i :3000 3. Test localhost: ping localhost 4. Test specific port: nc -zv localhost 3000 5. Check firewall: Ensure firewall allows local connections 6. Verify hosts file: Check for conflicting entries

API calls failing

Symptoms:

• API requests timeout
• SSL/TLS errors
• Connection refused

Checklist: 1. Test API endpoint: curl -v https://api.example.com 2. Check DNS: dig api.example.com 3. Verify SSL certificate: openssl s_client -connect api.example.com:443 4. Check proxy settings: Ensure no proxy interference 5. Test with different DNS: dig @8.8.8.8 api.example.com 6. Review API documentation: Verify endpoint URL and requirements

Hosts file not working

Symptoms:

• Domain resolves to wrong IP
• Changes not taking effect
• Still querying DNS servers

Checklist: 1. Verify hosts file syntax: cat /etc/hosts 2. Check for syntax errors: Spaces, valid IPs, correct format 3. Flush DNS cache: sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder 4. Test resolution: nslookup yourdomain.local 5. Verify hosts file priority: Should resolve before DNS 6. Check for duplicate entries: First entry wins 7. Restart browser: Clear browser DNS cache

Docker networking issues

Symptoms:

• Can't connect to containers
• Port mapping not working
• Network isolation problems

Checklist: 1. Check Docker network: docker network ls 2. Inspect container network: docker inspect container_name 3. Test container connectivity: docker exec container_name ping google.com 4. Check port mappings: docker ps (PORTS column) 5. Verify Docker daemon: docker info 6. Test localhost mapping: curl http://localhost:mapped_port

Quick reference: Essential commands

Connectivity:

ping example.com                    # Basic connectivity
ping -c 10 example.com              # Send 10 packets
nc -zv hostname port                # Test specific port

DNS:

nslookup example.com                # DNS lookup
dig example.com                     # Detailed DNS info
dig @8.8.8.8 example.com           # Query specific DNS server
host example.com                    # Simple DNS lookup
cat /etc/hosts                      # View hosts file
sudo dscacheutil -flushcache        # Flush DNS cache
sudo killall -HUP mDNSResponder    # Restart DNS resolver

Network info:

ifconfig                            # Network interfaces
netstat -rn                         # Routing table
netstat -an                         # Active connections
lsof -i                             # Processes using network
scutil --dns                        # DNS configuration

Troubleshooting:

traceroute example.com              # Network path
route get example.com               # Route to host
networksetup -getdnsservers Wi-Fi  # Current DNS servers

Tools to simplify network management

While command-line tools are powerful, managing network configurations and hosts file entries can be time-consuming. Locahl provides a modern interface for hosts file management on macOS, making it easy to:

• View and edit hosts file entries visually
• Validate syntax automatically
• Flush DNS cache with one click
• Enable/disable entries quickly
• Organize entries by project or environment
• Backup and restore configurations

For just €9.99, Locahl streamlines your development workflow and eliminates the need to manually edit hosts files and flush DNS caches. Perfect for developers managing multiple local projects and testing environments.

Conclusion

Network troubleshooting on Mac doesn't have to be frustrating. By following this systematic checklist—starting with basic connectivity tests, moving through DNS diagnostics, and checking system settings—you can quickly identify and resolve most network issues.

Remember: 1. Start with ping to test basic connectivity 2. Check hosts file before DNS queries 3. Use dig or nslookup for DNS diagnostics 4. Flush DNS cache after hosts file changes 5. Verify network settings in System Settings 6. Test incrementally and document findings

With these tools and techniques, you'll be able to diagnose and fix network issues faster, getting back to development work sooner. Keep this checklist handy, and don't hesitate to use tools like Locahl to simplify hosts file management and streamline your troubleshooting workflow.