WebRTC: ICE connection failed

Quick fix

Read the commands before running them. Anything that restarts a service, deletes data or changes permissions should be tried on a non-production system first.

// Watch which candidate pairs are tried
pc.oniceconnectionstatechange = () => console.log(pc.iceConnectionState);
const stats = await pc.getStats();

// STUN alone is not enough: most production calls need TURN
new RTCPeerConnection({ iceServers: [
  { urls: 'stun:stun.l.google.com:19302' },
  { urls: ['turn:turn.example.com:3478?transport=udp',
           'turns:turn.example.com:5349?transport=tcp'],
    username: 'user', credential: 'pass' },
]});

# Verify the TURN server from the network in question
npx turn-tester turn:turn.example.com:3478 -u user -p pass

# Corporate networks that block UDP need turns over TCP 443

How to diagnose Network errors

Network errors are precise if you read them literally. Connection refused means a machine answered and actively rejected: nothing is listening on that port. Timeout means nothing answered at all, which points at a firewall silently dropping packets or a wrong address. Connection reset means the peer accepted then abruptly closed, often a proxy, a protocol mismatch, or an application crash. Distinguishing those three saves most of the debugging time.

If the quick fix above does not resolve it, work through these steps. They apply to this whole class of error, not just to this one message, which is usually what saves the time.

1. Test layer by layer: ping for reachability, nc -zv host port for the port, then the application protocol. Do not skip to the application layer.
2. Confirm what is listening locally with ss -tulpn. "Connection refused" on localhost almost always means the service bound to 127.0.0.1 when it needed 0.0.0.0, or vice versa.
3. Capture packets when the error is ambiguous: sudo tcpdump -ni any port 443 and host x.x.x.x. A RST is visible; a silent drop is visible as unanswered SYNs.
4. For intermittent failures under load, check ephemeral port exhaustion and conntrack table limits (ss -s, conntrack -S) before blaming the network.
5. Suspect MTU when small requests succeed and large ones hang. Test with ping -M do -s 1472 and reduce until packets pass.

Tools worth reaching for

• ss -tulpn
• nc -zv
• tcpdump
• mtr
• curl --connect-timeout
• iptables -L -n -v

Authoritative references

Primary documentation for this error, worth reading before applying any fix in production.

📖 developer.mozilla.org

Related Network errors

• Bandwidth limit exceededNetwork bandwidth quota has been exceeded, causing connection throttling or blocking.
• bind: address already in use (EADDRINUSE)Another process is already listening on the port, or a previous server instance did not shut…
• chrony/NTP: clock not synchronised (Leap status: Not synchronised)The host's clock is free running because it cannot reach a time source or has rejected the…
• Circuit breaker openCircuit breaker pattern activated due to repeated failures, temporarily blocking requests to…
• Connection pool exhaustedAll available connections in the connection pool are in use, unable to create new connections.
• Connection refusedThe target server is not accepting connections on the specified port. The service may be…
• Connection reset by peerThe remote server abruptly closed the connection, often due to server overload or…
• Connection timeoutThe connection attempt took too long and was aborted. Network connectivity issues or server…

See all 35 Network errors →

Browse other categories

• HTTP 494xx client errors, 5xx server errors, redirects, headers and protocol problems.
• JavaScript 42npm resolution, async pitfalls, hydration, memory limits and runtime type…
• Database 41Connections, deadlocks, constraints, replication and memory limits.
• AI 35Rate limits, context windows, GPU memory and model-serving failures.
• Python 35Imports, virtual environments, encoding, concurrency and dependency conflicts.
• Kubernetes 34CrashLoopBackOff, ImagePullBackOff, OOMKilled, RBAC, scheduling and storage.
• Docker 27Daemon connectivity, disk space, image pulls, ports and architecture mismatches.
• System 26Disk space, systemd units, file descriptors, OOM killer and scheduled jobs.
• Cloud 25IAM permissions, quotas, service limits and credential failures.
• Security 25JWT validation, CSRF, OAuth grants, SELinux, SSH host keys and CSP.
• TLS 24Untrusted authorities, expiry, hostname mismatch, chains and cipher negotiation.
• Frontend 23Hydration mismatches, bundler resolution, layout shift and font loading.

Something missing or wrong?

This entry is maintained by hand. If the fix is out of date, incomplete, or you have a better one, email a correction and it will be reviewed.