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
```csharp
// 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)