UISP - Troubleshooting


This article addresses the most common issues related to UISP and provides instructions on how to solve them. To contact the UISP support team, and send them your UISP support info please create a support request. Please attach your support info to the request (if applicable). 

Note:  If you already have an open ticket about your issue, you can just reply to the last email you received from our support team and send the support info or any other additional information and requested files.

Common UISP application issues

My UISP doesn't start

UISP runs in docker containers. For that reason, the first step should always be to check on those containers by running the sudo docker ps command. In case, any container is failing, please run this command sudo tar -cvjSf /tmp/uisp-logs.tar.bz2 /home/unms/data/logs, download the uisp-logs.tar.bz2 file from the /tmp folder. and attach it to a support request as described in the Overview above (or send it as a reply if you already have an open ticket). Please include the output of the sudo docker ps command as well.

My device cannot connect to UISP

Each device needs to have a clear route to the UISP console in order to connect. There are three basic tools that can be used to check if the route from the device to UISP is free. Please note that some of those commands may be inaccessible on some devices

  1. ping
  2. traceroute
  3. curl

1, Use SSH to get into the device and try to ping the hostname of the UISP console. If the ping cannot go through, there is a network issue either in the device's configuration or on the route from the device. The connection can be also impossible if there is any packet loss or high latency (over 400ms).

Here are the other two commands that can be used to get more information about the network issue. . Replace the <UISP hostname> with the actual hostname of your UISP console and remove the <>:

2, Traceroute from the device to the UISP console:

traceroute -P ICMP <UISP hostname>

3, Check if the connection is upgraded to WebSocket:

curl --insecure --include --no-buffer --header "Connection: Upgrade" --header "Upgrade: websocket" --header "Host: example.com:80" --header "Origin: http://example.com:80" --header "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" --header "Sec-WebSocket-Version: 13" https://<UISP hostname>/

The output should look like this:

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: qGHgK3En71di5rrssAZTmtRTyFk=


If the device can ping the UISP hostname but it cannot connect anyway, please send us the output of these tests as well as support info of the device and your UISP. In order to send those files please follow the guide above.

My devices' connections are flapping

Note:  A flapping connection occurs when the device is repeatedly switching status from "Active" to "Disconnected", often within a narrow time frame.

As a first step, it is necessary to find out if the flapping is being experienced by the customers as well. If they are getting outages of internet service, then UISP is reporting the actual status just as it should. If customers report stable connection, the flapping is most likely caused by devices having issues connecting to the UISP console correctly. The two most common reasons for that are network issues and overload.

  • How to verify if it's a network issue: SSH into one of the flapping devices and run at least one hour-long ping pointed to the hostname of the UISP console. You can use this command
    ping -q -w 3600 your hostname here > /tmp/ping_result.txt &
    Please note that this command will run for an hour in the background. You need to wait before the ping's output will be saved in the ping_result.txt file located in /tmp folder. After the hour please check if there is any packet loss and/or latency over 400ms. If there is any packet loss or high latency then the flapping is caused by the network instability. For the UISP Cloud instances, please contact us as described in the Overview of this article, and in the Description let us know where the flapping devices are located (the country is sufficient).
  • How to verify if it's an overload issue: Check both the UISP console and the device for CPU and RAM load. For the UISP Cloud instances, please contact us as described in the Overview of this article, and in the Description let us know we need to check the load on the server. The device can be checked with the top command. 

It is also possible that the restart of the UISP will help. For self-hosted UISP instances, the restart can be done via CLI command, and for UISP Cloud users, there is an option to visit the UISP Cloud Access Portal and click on the restart button at the bottom of the screen.

Suspension / Traffic shaping is not working

For all advanced network features, UISP needs to know which IP address should be suspended/shaped. It is possible to check if the UISP knows that IP by opening the Subscribers view and making sure that the IP addresses column is enabled. Make sure that the IP address of the shaped/suspended device is there for the specific subscriber. In case the desired IP address is not present on that screen then:

  • Make sure that the desired IP address is not also the management IP address of the device. This is mostly relevant for devices in the bridge mode since those devices often have only one IP and it is the management one. There are several ways of solving this situation. One of them is to connect a Ubiquiti device downstream from the CPE, add that device to UISP, and then Suspend/Shape its IP address. Another way is to switch the device into a Router mode so that it has more IP addresses than just the management one. Lastly, it is possible to create a 3rd party device in UISP with the static IP address of the Client's downstream device. Please note that this will not work for 3rd party devices with dynamic IP.
  • Check the Settings > Network > Monitored IP subnets. The desired IP has to be in the range of this setting.

If everything seems to be configured correctly, please select one specific subscriber, go to the Subscribers view, and create a screenshot with the IP addresses column enabled. Mark the IP address on the screenshot so we know which one to look for. Then please use the method described above to send us that support file from the device that is assigned to the subscriber, the mentioned screenshot, and support info from a UISP gateway device. 

NetFlow is not working

For NetFlow, the same rules apply as for the other advanced network features (suspend, shaping). UISP has to know for which IP the traffic should be measured. That IP needs to be assigned to a specific Subscriber, and it has to be within Settings > Network > Monitored IP subnets range. Also, it is necessary to configure at least one router to provide NetFlow data to UISP. The ideal device for this is the main gateway since in most networks all the data is going through it. In case of issues with NetFlow, it is necessary to make sure that the router is sending Netflow data to the correct IP address and port. In our NetFlow article, there is a generic troubleshooting guide on how to perform that check.
In case the router is indeed sending NetFlow data to UISP but it is not displayed anyway, please send us a screenshot of the Monitored Subnets settings and NetFlow settings. Then select one client that is not displaying the NetFlow data and send us a screenshot of the Subscriber view where the subscriber is highlighted (make sure that the column IP addresses is enabled). Lastly, we need support info from the UISP and the device assigned to the affected subscriber. 

My Device is refused (AES key)

To understand this issue it is necessary to have a basic knowledge of the generic UISP key. When there is a mismatch between the AES key of the device and the record in the UISP database, the device will be refused immediately after connecting with the error message "Peer closed connection". There are two possible reasons:

  1. There is a generic AES key on the device but a specific AES key in the UISP database.
  2. There is a device-specific AES key in the device but no record of that device in the UISP database.

As a first step try to search for the device in UISP by using its IP or MAC address. If there is a record of the device UISP, then it most likely has the triangle error icon by its name and there should be the "Reset UISP key" button available for that device. Clicking on the button will reset the device-specific AES key recorded for that device's MAC address in the UISP database. The device should then connect automatically.  If not, then delete the device from UISP and insert the generic UISP key into its interface.
In case the device had no record in UISP then go to the "Devices" view and look for the "Add device" button. Click on the arrow next to that button and then click on the "Copy UISP key to the clipboard" link. Now you have the generic UISP key in your clipboard and you can insert it into your device. 
In case nothing helps, please contact us as described above. Make sure to include support info from the device and UISP. 

SMTP server not working

Listed below are some important settings and details when using a Gmail account for the configuration of the SMTP server in UISP. In order to receive email alerts from UISP, the SMTP server has to be configured. 

  • We recommend enabling the 2-Step Verification and generating an App password, which will be then used in the password field. 
  • If the Organization email is different from the Sender address in mailer settings, the outgoing emails may be limited or rejected on some SMTP servers. Note that the Organization email address is used in the email header attribute From (this will make the email look as if it came from that Organization's email address).
  • If the Organization email is different from the Sender address in mailer settings (which is typical for personal SMTP account email), it may cause the sending will fail on some SMTP servers.
  • Gmail SMTP server can use a different address or alias (other than the username of that particular Gmail account) but it is necessary to configure that address in the user's Gmail settings. See the Send emails from a different address or alias help article to learn more. Otherwise, the header attribute From will be replaced by the account user's username.
  • Personal Gmail accounts can send a maximum of 500 emails in a day and G Suite accounts can send a maximum of 2000 emails in a day. We recommend setting the Throttler configuration to accommodate these limits.

Google Maps not working (API key)

Here we discuss how to allow self-hosted UISP Application instances to display Google Maps and how to set up a Google API key. UISP Cloud instances do not have to configure a Google Maps API Key since it is already set up using Ubiquiti's own API Key.

ATTENTION: Since July 16th, 2018 it is mandatory to enable billing with a credit card and have a valid API key for all Google projects.

Before Google Maps API can be used, you must make sure the required APIs are enabled in your Google API console.

To view your list of enabled APIs:

  1. Go to the Google API console.
  2. Select or create your project.
  3. First, go to the Dashboard and click on the 'Enable APIS and Services' button. You will see a list of different APIS. Use the search box to find Geocoding API, Maps Elevation APIMaps JavaScript API, Places API for Web and enable it. 

To create the API Key, follow the steps listed below:

  1. Go to the Google API console.
  2. Select your project.
  3. Select Create credentials and API key in the corresponding menu.
  4. Your API key will then be created and you can use it in Settings → UISP → Google Maps API Key. UISP Cloud instances will not have this option since users will not have to configure this themselves: it has already been set by default using our own Google Maps API key.
  5. If you want, you can restrict the key to your domain to prevent unauthorized use and quota theft.

Common UISP Console issues

Here we list the most common issues encountered by users when using the UISP console device accompanied by the recommended steps to solve them.

UISP Console - UI account is not bound to the local one

Please make sure that you are signed in with the correct AI account. If you open the UISP Cloud Access Portal, you should see the UISP console there. If you are not sure which UI account is the right one, please contact support.

Common UISP Cloud Issues

Here we list the most common issues encountered by users when using the free UISP Cloud accompanied by the recommended steps to solve them.

User Tips: Check the Ubiquiti System Status page to determine if there is an outage or if the UISP Cloud service is running.

UISP Cloud - Forgotten Password

It is important to distinguish between the local password of the UISP Cloud instance (<your hostname>/uisp.com) and the log-in to the UISP Cloud Access Portal (uisp.com). The Access portal is where the Cloud instance is managed and it uses the UI Account credentials (the same credentials which are used to access Ubiquiti community forums).
Please log in the UISP Cloud Access Portal (uisp.ui.com) using your Ubiquiti (UI) credentials, it is necessary to log in with the same UI credentials as the one used for creating the UISP Cloud application.

Please click the 3 dots in the right corner → it will open a popup window with possible actions:
Local UISP Cloud instance passwords can be managed by clicking on the Manage UISP users icon. This will open a popup window with a list of UISP users present in this UISP Cloud instance. 
Select the user that needs a password reset and click on the three-dot menu on the right. An option to reset the password will appear. The same method can be used to disable two-factor authentication (2FA).

ATTENTION: In case the local login is not working, make sure that the email address was not used instead of the login name.

UISP Cloud - Single Sign-On Authentication failed

If there is the error message Authentication failed please click on the arrow at the top left to go back to the main login screen and use the Sign in with the local account link. It is possible to change local account credentials through the method described above. 

ATTENTION: In case the local login is not working, make sure that the email address was not used instead of the login name.

This error is most likely caused by disabled UI Account access for the specific user. When local credentials are used to access UISP, please go to Settings -> Users edit the specific user, and enable the Ubiquiti single sign-on. 

UISP Cloud - The UISP instance is Missing

If there is no active instance present when the UISP Cloud Access Portal is opened and there is no record of any UISP instance, do not worry. We keep data backups for at least a month. Please use the Ubiquiti support request form, provide the hostname of the instance, and we will recover the instance to the state before it was suspended.

UISP Cloud - The Application is Stuck in a Restarting Loop

There may be several causes for this, but there is no reason to worry. Cloud data is backed up on UISP servers for at least a month. Please use the Ubiquiti support request form, provide the hostname of the instance, and the Ubiquiti community username and we will make sure the UISP instance runs again.

UISP Cloud - Device limits

In order to use the free UISP Cloud, you must connect and maintain:

  • At least 1 active Ubiquiti device within the first 24 hours of using this service.

Note:  Only Ubiquiti devices that are currently connected or were connected within the last two days, count towards this limit. The device needs to have the UISP key written in its configuration and it needs to communicate with UISP to be counted. 

In order to continue using UISP Cloud, it is necessary to keep devices connected and active, otherwise, they are not counted towards this limit. In case any device is disconnected it will be still counted as active for up to two days. If that device connects within those two days—even for a second and then disconnects again, the timer resets, and the two-day grace period starts again. When the minimum device limit is not met, there will be a notification on the UISP interface and the system will send an email message. If the device limit is not met after that, then the Cloud controller will be disabled and eventually deleted.

Please note that in such a case, it is possible for others to use the hostname for their own instance. Make sure to reclaim the hostname at your earliest convenience to avoid this situation. The longer the hostname is not used the bigger the chance someone else may pick it up.

UISP Cloud - After logging in, there is a "UISP is starting" message with a picture of a rocket

This means the UISP application is having some issues starting. If you see this for a prolonged period of time please contact our support by using the Ubiquiti support request form, and let us know the hostname of the instance. We will analyze and fix the situation.

Any other issue

If there is an issue we did not list here, feel free to contact us by submitting a request. Feel free to attach screenshots (ideally of the whole screen) since they are often useful to give us a clear idea of the situation at hand, and as much description as possible.

Was this article helpful?
559 out of 795 found this helpful