Overview

This article describes the possible causes and solutions for when the UniFi Network 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 and requirements 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: Verify that the username 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.

<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)
 ...

Or:

<launcher-monitor> ERROR launcher - Port 8080 is used by other programs

3. Change the ports used by UniFi Network 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 Network Controller. Please use Java 8. The Controller software release notes which can be found along with the software in our Downloads page will have notes and requirements for each release.

Solution: Ensure that the correct Java version is installed on the machine (64-bit). Beginning with UniFi Network Controller 5.10.12, it is required to use x64 Java as we only support 64-bit WebRTC Library. Uninstall Java if present and install Java 8.

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 Network 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 Network Controller. 

Solution: Use only supported MongoDB versions as stated in the controller's release notes (currently it is version 3.4). 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