UniFi - Controller Fails to Start When Opened


Overview


This article describes the possible causes and solutions for when the UniFi Controller fails to start when opened. Use the table of contents below to navigate through the different causes.

NOTES: Before troubleshooting, please verify that all steps for software installation in the UniFi User Guide have been followed.

Table of Contents


  1. Windows Profile Username has Special Characters
  2. Needed Ports are Unavailable
  3. Java Incompatibility
  4. Not Enough Space on the Host System
  5. Database Corruption
  6. Incompatible MongoDB Version
  7. Related Articles

Windows Profile Username has Special Characters


Back to Top

Issue: The controller's database (mongo) will not start because it cannot find a file. 

Solution: Change the username and make sure it has no special characters (including accents, for example: á, ë, ì, ô, ç, ã).


Needed Ports are Unavailable


Back to Top

Issue: Ports needed by UniFi are being used by other programs.

Solution: Change ports following the steps outlined below.

1. Take a look at <unifi_base>/logs/server.log

NOTE: The location <unifi_base> will vary depending on your operating system. See this article for more information.
[2011-06-01 22:09:14,145] <UniFi> ERROR StandardServer - StandardServer.await: create[8081]:

2. Most likely, there will be an ERROR similar to this:

java.net.BindException: Address already in use: JVM_Bind
 at java.net.PlainSocketImpl.socketBind(Native Method)
 ...

3. Change the ports used by UniFi Controller, as seen in this article: UniFi - Changing Default Ports for Controller and UAPs


Java Incompatibility


Back to Top

Issue: Currently, Java 9 is not supported for the UniFi Controller. Please only use Java 8. The Controller software release notes which can be found along with the software in our Downloads page will have information on what is supported for each release.

Solution: Ensure that the correct Java version is installed on the machine (32-bit/64-bit). We recommend 64-bit Java for all new installs. 32-bit should only be used when absolutely necessary.


Not Enough Space on the Host System


Back to Top

Issue: Data retention on some systems may be set too high leaving the host without sufficient storage for new data. If the database cannot allocate the storage space for new information, the UniFi Controller can start to malfunction.

This scenario can produce a log in the mongo.log file as such:

Wed Nov 21 10:11:54.435 [initandlisten] ERROR: Insufficient free space for journal files
NOTE: The location mongo.log will vary depending on your operating system. See this article for more information.

Solution: Our UniFi - How to Remove (Prune) Older Data and Adjust Mongo Database Size article includes instructions and a script for database cleanup and reduction.


Database Corruption


Back to Top

Issue: Database corruption can lead to a state in which the Controller cannot read the database documents. Typically this would throw errors in mongo.log or in server.log. Database errors can also throw Java errors of many varieties into server.log.

The file named server.log can be found in <unifi_base>/logs.

NOTE: The location <unifi_base> will vary depending on your operating system. See this article for more information.

This can look like the following in server.log:

[2018-11-21 19:36:08,379] <launcher> INFO db - Connecting to mongodb://127.0.0.1:27117
[2018-11-21 19:36:09,949] <db-server> ERROR system - [exec] error, rc=100

Solution: The following article will explain how to alleviate database corruption: UniFi - Network Controller: Repairing Database Issues on the UniFi Controller.


Incompatible MongoDB Version


Back to Top

Issue: This issue would typically arise for those who are installing on a Debian-based Linux host. In newer versions of Ubuntu such as 18.04, the bundled MongoDB version 3.6 is unsupported by the UniFi Controller. 

Solution: To check the MongoDB version installed use this command in terminal or CLI:

mongod --version

Related Articles


Back to Top

UniFi - Where is <unifi_base>?

UniFi - Changing Default Ports for Controller and UAPs

UniFi - How to Remove (Prune) Older Data and Adjust Mongo Database Size

UniFi - Network Controller: Repairing Database Issues on the UniFi Controller


We're sorry to hear that!