Basic Debugging Steps for ICE Connectivity

When diagnosing ICE connectivity issues, the first step is to check if the required ICE candidates are being gathered correctly.

1. Check Number of Candidates Gathered

Ex:

2. No SRFLX - UDP Candidates?

• This means the app couldn’t get server-reflexive candidates using the STUN server.

• Next Step:

  • Check for ICE Candidate Errors (see section below).

  • If no errors are found related to the STUN server, it's likely that STUN is not configured at all.

• Resolution:

  • Ask the customer to configure a valid UDP STUN server in their ICE server config.

3. No RELAY - UDP Candidates?

• This means the app couldn’t get relay candidates from the TURN server.

• Next Step:

  • Check for ICE Candidate Errors (see below).

  • If no errors are found related to the TURN server, it's likely that TURN is not configured.

• Resolution:

  • Ask the customer to configure a valid UDP TURN server in their ICE server config.

4. Debugging ICE Candidate Errors

Error Code: 701
Meaning: Server could not be reached (e.g., DNS or firewall block)
What to Check:

• Verify that the STUN/TURN server URL is correct.

• Ensure the server is reachable from the client’s network.

• We can check this by using a different agent's laptop to troubleshoot with same voice application or try to reach this url thrid party ice test (this will be added to Agent Troubleshooting later)

• If unreachable, check firewall rules and whitelisting settings.

​

Error Codes: 401 / 403
Meaning: Unauthorized / Forbidden
What to Check:

• Confirm that the TURN credentials (username/password) are correct and properly configured.

​

Error Code: 438
Meaning: STUN/TURN allocation mismatch
What to Check:

• Verify if the server supports TURN.

• Check for misconfiguration on the TURN server.

Error Codes: 500+
Meaning: Server error
What to Check:

• These errors indicate an issue on the TURN server side.

• Contact the TURN server provider to raise and resolve the issue.

Possible causes and steps based on the message shown:

1. Direct Connection Established

Message Shown:

✅ Connection successful! You are directly connected for the best experience.

​

What it means:
The app connected you directly to the other person using the peer-to-peer UDP connection

What you should do:
Nothing. Everything is working perfectly.

2. Connected via Relay Server

Message Shown:

⚠️ Direct connection was not possible, so we’re using a relay server. This may cause slight delays, but you’re connected.

​

What it means:
A direct connection wasn't possible — likely due to network restrictions — so the app is using a relay server to connect the peers. This might cause a bit more delay, but you’re still connected.

Common Cause:
Your network may be using Symmetric NAT, which blocks direct peer-to-peer connections.

What you should do:

• If the call quality is fine, you don’t need to do anything.

• If you notice lag, check with IT to see if they allow peer-to-peer traffic.

3. No Way to Connect

Message Shown:

❌ We couldn’t find a way to connect. Please check your network or firewall settings, or try a different internet connection.

​

What it means:
The app is unable to gather ice candidates for attempting a connection. This often happens if your firewall or network is blocking connection attempts or if required servers are not allowed by your network.

Common Cause:

• UDP and TCP ports are blocked

• Firewall is blocking the connection

• STUN/TURN servers are not reachable or not configured

What you should do:

• Try switching networks (e.g., mobile hotspot)

• Disable firewall or VPN temporarily to test

• Ensure the app’s servers are allowed on your network (contact IT if unsure)

4. UDP Blocked, Connected via TCP

Message Shown:

⚠️ UDP connections are blocked on your network, but we connected using TCP. For the best experience, please allow UDP traffic.

​

What it means:
The app couldn't use the faster UDP connection, but it managed to connect using TCP. This fallback works but less reliable.

What you should do:

• Ask your network administrator to allow UDP traffic

• Ensure STUN/TURN servers are allowed through firewalls

• If possible, try using a different network

5. TCP Tried, But Connection Failed

Message Shown:

❌ We couldn’t establish a connection using TCP fallback. Please check your firewall and TURN server settings, or try a different network.

​

What it means:
Only TCP connections were tried — and even those didn’t work. UDP is likely blocked, and the app couldn’t fall back successfully.

Common Cause:

• Firewall blocks UDP

• Symmetric NAT and no relay setup

What you should do:

• Allow UDP and TCP connections in firewall

• Try switching to a more open network

6. Candidates Found, But Connection Failed

Message Shown:

❌ Connection attempts failed despite available options. Please check your firewall and network configuration or contact support.

​

What it means:
The app found connection options (called "candidates") but none of them worked. Something on the network is still blocking the connection.

Common Cause:

• Strict NAT/firewall setup

• TURN servers not configured

• No route between the peers, even with fallback

What you should do:

• Contact your network admin to allow required traffic

• Ensure TURN servers are properly set up

• Try switching to a different network