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, including a final fallback using a STUN server.
Principle: For security and privacy reasons, modern browsers (Chrome, Firefox, Edge) use mDNS (Multicast DNS) addresses (e.g., host.local) instead of real IP addresses when gathering local ICE candidates. The receiving end (the device) must
resolve these mDNS addresses via mDNS resolution—sending and receiving multicast packets—to obtain the actual IP address. If the device cannot perform this resolution, the WebRTC handshake fails.
Symptom: The browser PC and the PortableRTC device are on the same LAN, but the WebRTC connection never establishes. The browser may show "failed" or "disconnected" after several seconds.
Root Cause: In most cases, this is caused by the PortableRTC device (or the embedded WebRTC peer) failing to resolve the browser's mDNS address. This can be due to incorrect gateway settings, multicast isolation between Wi-Fi and Ethernet, or browser proxy configurations.
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. Please check the network environment and configuration in the following order. Each step targets a common cause of mDNS failure.
Action: Verify that the PortableRTC device is configured with the correct Gateway Address (default route).
Reason: Without a proper gateway address, the device may be unable to send or receive multicast packets correctly. mDNS relies on multicast traffic, which often requires a valid route to the local subnet and the ability to send packets to the multicast group. A missing or incorrect gateway can disrupt multicast forwarding even within the same LAN.
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 eth0Action: 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 consumer and enterprise routers enable AP Isolation or multicast-to-unicast conversion, which prevents multicast packets from being forwarded between Wi-Fi clients and wired clients. Some routers also isolate multicast traffic between different VLANs or guest networks. This directly blocks mDNS resolution.
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:
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.If none of the above methods work, it is recommended to modify the signaling server configuration file, configure the STUN server address in the <ice_servers> node, and run the STUN server. This way, the P2P connection can be successfully established
within the local area network.
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. The PortableRTC device and browser will fall back to using the STUN server to obtain and validate candidate addresses.
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.
| Symptom / Cause | Quick Fix | Applies to Step |
|---|---|---|
| Device has no default gateway | Set correct gateway IP (router’s LAN IP) | 1 |
| Mixed Wi-Fi + Ethernet with AP isolation | Connect both devices via same media (both Ethernet or both Wi-Fi) | 2 |
| Browser proxy or WebRTC flags blocking mDNS | Disable proxy, reset browser flags, or test incognito mode | 3 |
| Persistent mDNS failure despite above | Add STUN server to <ice_servers> configuration |
4 |
WebRTC connection failures in a LAN environment are often due to mDNS resolution issues introduced by modern browser privacy features. By systematically checking gateway configuration, avoiding multicast isolation, adjusting browser settings, and finally deploying a STUN server as a fallback, you can restore reliable P2P connectivity. For most cases, either aligning connection methods or adding a STUN entry to the signaling server configuration resolves the problem without requiring network hardware changes.
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.