Troubleshooting WebRTC Connection Failures in LAN

Diagnose and resolve mDNS resolution issues, gateway misconfigurations, and multicast isolation — with STUN fallback for robust local P2P connections.

WebRTC enables real-time peer-to-peer communication, but establishing a connection within a Local Area Network (LAN) can sometimes fail unexpectedly. Even when both the browser and the target device (e.g., PortableRTC) are on the same subnet, the connection may time out or never reach the "connected" state. This guide explains the root cause — mDNS resolution — and provides step-by-step troubleshooting steps to fix the issue, starting with a quick HTTPS fix and ending with a STUN server fallback.


1. Core Principle & Background

Principle: For security and privacy reasons, modern browsers handle local IP address exposure differently depending on the protocol:

Symptom: The browser PC and the device are on the same LAN, but the WebRTC connection fails to establish.

Root Cause: In most HTTP-based setups, the failure is caused by the device being unable to resolve the browser's mDNS address due to network restrictions.

📡 mDNS in a nutshell: When a browser generates a local ICE candidate over HTTP, it may produce a candidate like mdns://abc123.local instead of 192.168.1.100. The remote peer must send an mDNS query to the multicast address 224.0.0.251 (or ff02::fb for IPv6) and wait for a response. Any network or device limitation that blocks multicast packets breaks this process. Under HTTPS the browser skips mDNS entirely, which is why HTTPS is the fastest fix below.

2. Troubleshooting Steps

Please check the network environment and configuration in the following order. Each step targets a common cause of mDNS failure.

1 Recommended — Quick Fix: Use HTTPS Instead of HTTP

Action: Since HTTPS allows browsers to expose the real local IP address directly, switching to HTTPS URLs can bypass the mDNS resolution issue entirely.

Change your WebRTC stream URL from:

http://[http_server_ip]:[http_port]/webrtc?streamid=...

to:

https://[https_server_ip]:[https_port]/webrtc?streamid=...
💡 Tip: If you have already configured HTTPS on the PortableRTC, this single change often resolves the connection problem immediately. Only proceed to the following steps if HTTPS is unavailable or does not work in your environment.
2 If HTTP is Required: Check Gateway Configuration

Action: Verify that the PortableRTC device is configured with the correct Gateway Address (default route).

Reason: Without a valid gateway, the device may be unable to send or receive multicast packets, causing mDNS resolution to fail.

How to verify: On the PortableRTC device, check the network configuration (via CLI or web interface). Ensure the gateway IP matches your router's LAN IP (e.g., 192.168.1.1). Also, verify that the subnet mask is correct.

# Example (Linux-based device)
ip route show default
# Should output something like: default via 192.168.1.1 dev eth0
3 If HTTP is Required: Check Connection Method (Multicast Isolation)

Action: Ensure that the browser PC and the PortableRTC device connect to the router using the same physical method (both Wi-Fi or both Ethernet).

Suggestion: If possible, connect both devices via Ethernet cable, or both via the same Wi-Fi SSID. Avoid mixed connections (one wired, one wireless) unless you have verified that your router allows multicast traffic between the two interfaces.

Reason: Many routers enable AP Isolation or multicast filtering, which prevents multicast packets from being exchanged between wireless and wired clients. Some routers also isolate multicast traffic between different VLANs or guest networks. This directly blocks mDNS resolution.

⚠️ Test tip: Temporarily connect both devices to the same switch or the same Wi-Fi network and retest. If the connection succeeds, the issue is multicast isolation. You may need to disable "AP Isolation" or "Client Isolation" in your router settings.
4 If HTTP is Required: Check Browser Settings

Action: Check for special network proxy settings in the browser, or try resetting the browser settings to default and retest.

Reason: Browser extensions, proxy configurations, or flags that modify WebRTC behavior (e.g., "WebRTC IP handling policy") can interfere with mDNS candidate generation or ICE processing. Also, some enterprise proxies block UDP or multicast traffic used by mDNS.

What to do:

  • Disable any VPN or proxy extensions temporarily.
  • Go to chrome://flags/#enable-webrtc-hide-local-ips-with-mdns (Chrome) and try disabling "Anonymize local IPs exposed by WebRTC" — though note that modern browsers have this on by default; disabling it may reveal real IPs but can be used as a test to confirm mDNS is the cause.
  • Reset browser settings to default (Settings → Reset and clean up → Restore settings to their original defaults).
  • Test using a different browser (e.g., Firefox vs Chrome) to see if the issue is browser-specific.
5 Last Resort: Configure STUN Server in Signaling Server

If none of the above methods work, modify the signaling server configuration file as follows:

Steps:

  1. Add a STUN server address inside the <ice_servers> node.
  2. Run the STUN server service.

Why this works: A STUN server helps endpoints discover their public IP and port mappings, but it also provides a reliable way to exchange ICE candidates when mDNS fails. In a LAN environment, a locally hosted STUN server (or even a public one like stun:stun.l.google.com:19302) can assist with candidate gathering and resolution, bypassing the need for mDNS. This allows the P2P connection to be established successfully even within a restrictive LAN environment, as the STUN server can help exchange the correct external (or reflexive) candidates when local mDNS resolution is not feasible.

Configuration example (for HappyTime Signaling Server or similar):


<ice_servers>
    <url>stun:stun.l.google.com:19302</url>
    <!-- or run your own STUN server locally -->
    <url>stun:192.168.1.200:3478</url>
</ice_servers>

If you run your own STUN server on the LAN (e.g., using coturn or a simple STUN implementation), ensure the device and browser can reach it on the configured port (default 3478). After updating the signaling server configuration, restart the signaling service and retest the WebRTC connection.

💡 Pro tip: For production environments, consider using a TURN server as a fallback when STUN fails, but for LAN troubleshooting, a STUN server is usually sufficient to resolve mDNS-related issues.

Summary Table: Causes & Quick Fixes

Symptom / Cause Quick Fix Applies to Step
HTTP + mDNS resolution failure (most common) Switch the WebRTC URL to HTTPS to expose the real local IP 1
Device has no default gateway Set correct gateway IP (router's LAN IP) 2
Mixed Wi-Fi + Ethernet with AP isolation Connect both devices via same media (both Ethernet or both Wi-Fi) 3
Browser proxy or WebRTC flags blocking mDNS Disable proxy, reset browser flags, or test incognito mode 4
Persistent mDNS failure despite above Add STUN server to <ice_servers> configuration 5

Conclusion

WebRTC connection failures in a LAN environment are often due to mDNS resolution issues introduced by modern browser privacy features over HTTP. Because HTTPS lets browsers expose real local IP addresses directly, switching the WebRTC URL from HTTP to HTTPS is the fastest and most reliable fix. If HTTPS is unavailable, systematically check the gateway configuration, avoid multicast isolation, and adjust browser settings; finally, deploying a STUN server in the signaling server <ice_servers> node provides a robust last-resort fallback for restrictive LAN environments.

If you continue to experience failures, please contact HappyTime support with the following information: network topology (router model, connection methods), browser console logs (WebRTC internals), and the output of the diagnostic commands above. Our team is ready to assist.

📚 Related resources: WebRTC ICE & mDNS specification