Northbound/Assets/Scripts/CONNECTION_TROUBLESHOOTING.md

Connection Failure Troubleshooting Guide

Problem: "Failed to connect to server" error

Quick Fixes to Try

1. Add NetworkDebugger to scene

   • Add NetworkDebugger component to NetworkManager
   • Check Console for detailed connection logs
   • Look for:
     • Connection approval status
     • Transport binding errors
     • Timeout messages

2. Add NetworkConnectionFixer to scene

   • Add NetworkConnectionFixer component to NetworkManager
   • Right-click component → "Fix All Known Issues"
   • This auto-fixes common transport timeout issues

3. Check Firewall (Most Likely Cause) Even with port forwarding, Windows Firewall may block connections:

   Windows:

   • Windows Security → Firewall & network protection → Allow an app through firewall
   • Add Unity Editor AND your built executable
   • Allow on both Private and Public networks
   • Add exception for port 7777 (or your port)

   Command Line (Quick Fix):

   netsh advfirewall firewall add rule name="Unity Network" dir=in action=allow protocol=TCP localport=7777
   

4. Verify Transport Settings In Play mode, on NetworkManager → UnityTransport:

   • ConnectionData.Address should be 0.0.0.0 for Host/Server
   • ConnectionData.Port should be 7777 (or your forwarded port)
   • ServerListenAddress can be left default

5. Test Port Forwarding

   • Use online tool: https://www.yougetsignal.com/tools/open-ports/
   • Enter your public IP and port
   • Should show "Open" (not "Closed" or "Timed out")

6. Disable IPv6 (Temporary Fix) Some network configurations have IPv6 issues:

   Control Panel → Network and Internet → Network Connections
   → Right-click adapter → Properties → Uncheck Internet Protocol Version 6
   

   (Reboot required)

7. Increase Network Timeouts

   • On UnityTransport component:
   • Connect Timeout MS: 15000 (15 seconds)
   • Max Connect Attempts: 10

Debug Steps

1. Check Server Side

Add NetworkDebugger → Play → Start Host
Check Console for:
  ✓ "Server Started Successfully"
  ✓ "Listening on: 0.0.0.0:7777"
  ✗ Any binding errors

2. Check Client Side

Add NetworkDebugger → Play → Connect to PUBLIC IP
Check Console for:
  ✓ "Connection Approval Request from Client"
  ✓ "Approval Response: Approved: true"
  ✗ "TRANSPORT FAILURE"
  ✗ "Failed to connect to server"

3. Common Error Patterns

Error: "Failed to connect to server" + "TRANSPORT FAILURE"

• Cause: Firewall blocking
• Fix: Allow Unity through firewall, check port forwarding

Error: Connection approval never happens

• Cause: NetworkManager configuration issue
• Fix: Check NetworkConfig → Connection Approval = true

Error: Client shows "Connected" but no player spawns

• Cause: ConnectionApproval returning false or spawn point issues
• Fix: Check NetworkConnectionHandler logs

Advanced Troubleshooting

Log Network State

// Add this component and right-click → "Log Current Network State"
public void CheckConnection()
{
    Debug.Log("IsServer: " + NetworkManager.Singleton.IsServer);
    Debug.Log("IsClient: " + NetworkManager.Singleton.IsClient);
    Debug.Log("IsConnectedClient: " + NetworkManager.Singleton.IsConnectedClient);
}

Test Local Connection First

1. Host: Connect to 127.0.0.1 (should always work)
2. If fails: Project setup issue, not network issue
3. If works: Network/Firewall issue with public IP

Check NetworkManager Configuration

Ensure:

• Player Prefab assigned
• Network Prefabs list populated
• Connection Approval enabled
• Scene Management enabled (if using scenes)
• Transport is Unity Transport (UTP)

Alternative Solutions

Option 1: Use LAN instead of Internet

If possible, use VPN or Hamachi:

• Creates virtual LAN
• Both players appear on same network
• No port forwarding needed

Option 2: Use Relay Service

Unity Relay bypasses NAT/Firewall:

• Requires Unity Services account
• Free tier available
• More reliable for internet play

Option 3: Dedicated Server

• Host on cloud server (AWS, Azure, etc.)
• No port forwarding needed on client side
• Better performance and reliability

Quick Checklist

• Port forwarded correctly (verify with online tool)
• Firewall allows Unity/Build executable
• Using public IP (not 127.0.0.1 or 192.168.x.x)
• Same Unity version and Netcode version on both sides
• Same port on both client and server
• NetworkManager has Player Prefab assigned
• Host started BEFORE client tries to connect
• No antivirus/security software blocking
• Both using Release builds (not Debug)

When to Ask for Help

If you've tried:

1. All firewall fixes
2. Verified port forwarding with online tool
3. Tested local connection (127.0.0.1) works
4. Checked NetworkManager configuration
5. Added NetworkDebugger and NetworkConnectionFixer

Then share:

• Full Console logs from BOTH host and client
• NetworkManager inspector screenshot
• UnityTransport settings screenshot
• Port forwarding confirmation (screenshot or online tool result)