UniFi - Troubleshooting STUN Communication Errors

Overview


This article is meant to help resolve errors concerning STUN connectivity between the UniFi managed devices and the UniFi controller.

Table of Contents


  1. Introduction
  2. What is STUN?
  3. Requirements
  4. Why has this error suddenly appeared?
  5. How to Resolve this Error
  6. How to Add a STUN Port Forwarding Rule in UniFI
  7. Verify Proper UniFi Controller Inform URL
  8. Related Articles

Introduction


Beginning in UniFi controller version 5.6.x+, customers may have noticed the presence of a new error message that appears in the UI associated with UniFi devices. A warning sign may be visible next to the Connected device as shown:

If you click on the device and expand the error at the top of the device properties pane you will see a "STUN Communication Failed" error with the following details:

This error indicates that the controller is not able to properly connect via the STUN protocol with this particular device, which can prevent some of the features in the UniFi controller like device Debug Terminal from working properly. This document will explain what these errors mean and how to troubleshoot and resolve them.

What is STUN?


Back to Top

STUN stands for Session Traversal Utilities for NAT, and includes a set of protocols used in networking to better handle communication when going through network address translation (NAT). In simple terms, STUN provides a way for devices to securely communicate with other devices when they're located behind a router. This is necessary because the devices in your network have individual IP addresses that are used to communicate internally, but not known to servers/clients outside of your network. STUN when used by a particular application, will go and initiate a connection with a public STUN server and request to know what address will be used by the STUN server to communicate with the device through its router.

UniFi Devices use STUN to properly communicate with the UniFi controller. In this case, the UniFi controller acts as the STUN server. In order for STUN communication to work properly, the UniFi device must be able to resolve to the UniFi controller via the inform URL, and communicate with the address via port 3478.

UniFi requires STUN connectivity for a variety of functions, for example, locating devices through the controller UI, as well as to initiate contact and communicate details from the device to the controller.

Requirements


In order for STUN to work properly, the client devices need to be able to resolve to and communicate over UDP port 3478 with the UniFi controller. UDP Port 3478 must be open inbound on the controller machine.

Why has this error suddenly appeared?


Back to Top

A number of UniFi administrators may have noticed the sudden appearance of this error after upgrading to controller versions 5.6.x+. Since this error message was only recently added in the controller UI in versions 5.6.x+, this doesn't reflect an issue with STUN on these versions, but in most cases is bringing more attention to a previously existing issue.

How to Resolve this Error


Back to Top

If this issue is encountered immediately after initial device adoption, try refreshing the controller page/giving this a few minutes for STUN to properly connect.

In cases where this persists for longer periods of time, this error message most often results from a connectivity issue with STUN from the device to the UniFi controller. To resolve this, make sure to open UDP port 3478 on your controller machine firewall and ensure that your router is properly relaying STUN traffic to the UniFi controller from the UniFi devices.

If you are using your UniFi controller to manage devices that are not located behind the same router, you will need to setup a port forward similar to how you created one for the inform packets to be forwarded to the controller using port 8080.

How to Add a STUN Port Forwarding Rule in UniFI


Back to Top

 

NOTE:

The following directions require the presence of a UniFi Security Gateway to be effective. If you have another router, follow similar method using the router’s configuration method.

1. To do this with a USG, go to Settings > Routing & Firewall > Port Forwarding and "Create New Port Forward Rule"

2. Fill out these fields similar to the following example, using the IP address of your UniFi controller in the Forward IP field, and UDP ports 3478 in both port fields:

3. Click “Save” to apply these changes. After some time, or if you restart your device, the error message should no longer be visible.

Verify Proper UniFi Controller Inform URL


Back to Top

If after verifying the controller firewall, and the router are not blocking traffic, you may need to verify that the device hasn’t been configured with an incorrect inform URL. This setting can be found in the controller under Settings > Controller

If the checkbox next to “Override inform host with controller hostname/IP” is checked, make sure the controller hostname/IP is publicly accessible to devices that are being managed outside of your controller’s local network, otherwise this will provide the wrong STUN URL to the UniFi Devices. If the hostname/IP would only be accessible locally to the device, uncheck this box and click “Apply Changes”. 

Note that 192.168.1.6 is only the IP in this example, yours will likely be a different hostname/IP address. 

Related Articles


Back to Top