Unifi Controller Startup Failed: Fixes That Work

If the UniFi Controller (Network Application) fails to start, the cause is almost always a port conflict, a corrupted MongoDB database, or a Java version mismatch, and the fix usually takes under ten minutes. This article walks you through the exact steps to diagnose and resolve the startup failure on Windows, macOS, and Linux, so you can get your UniFi network back online.

Background: What the UniFi Controller Does

The UniFi Controller (now officially called the UniFi Network Application) is the software that manages UniFi access points, switches, and gateways. It runs as a Java application with an embedded MongoDB database, and it provides a web-based dashboard for configuration, monitoring, and guest management. The controller must be running for your UniFi devices to be managed, though existing network traffic continues to flow if the controller goes down.

Because the controller bundles Java and MongoDB, startup failures often stem from conflicts between these components and your operating system or other installed software.

Common Causes of Startup Failure

Before you start troubleshooting, it helps to know what you are looking for. The most frequent culprits are:

• Port conflicts – The controller uses several ports (most commonly 8080 for device communication, 8443 for the web UI, and 8843 for the guest portal). If another program is using one of these, the controller will fail to start.
• Corrupted MongoDB data – A crash or power loss can corrupt the database files, preventing the controller from initializing.
• Java version issues – The controller requires a specific Java version. If you have an incompatible version installed, or if the bundled Java is missing, startup will fail.
• Insufficient disk space or permissions – The controller needs to write to its data directory. If the disk is full or the service account lacks permissions, it will fail.
• Outdated firmware or software – Upgrading the controller or your devices can sometimes introduce compatibility issues.

How to Diagnose the Exact Error

To fix the problem, you need to know what the controller is complaining about. The quickest way is to check the logs.

1. Find the log directory. On Windows it is typically C:\Users\<username>\Ubiquiti UniFi\logs, on macOS ~/Library/Logs/UniFi, and on Linux /usr/lib/unifi/logs or /var/log/unifi.
2. Open server.log in a text editor. Look for lines containing ERROR, Exception, or FATAL.
3. If you see BindException: Address already in use, it is a port conflict. If you see MongoException or No space left on device, it is a database or disk issue.

If you cannot open the log, try starting the controller from the command line to see the error directly. On Linux, run sudo service unifi start and then check sudo service unifi status. On Windows, run java -jar lib\ace.jar start from the UniFi installation directory (usually C:\Program Files\Ubiquiti UniFi).

Step-by-Step Fixes

Here are the most effective fixes, in order of likelihood and ease.

1. Check for Port Conflicts

If the log shows a port conflict, identify which process is using the port. On Windows, run netstat -ano | findstr :8080 (replace 8080 with the conflicting port). On macOS/Linux, run lsof -i :8080. You will see the PID of the process. Then either stop that process (if it is safe) or change the controller’s port in system.properties (located in the UniFi data directory). For example, change unifi.http.port=8080 to unifi.http.port=8081. After changing the port, restart the controller.

2. Repair MongoDB Database

If the database is corrupted, you can often repair it. Stop the controller, then run the following command from the UniFi installation directory:

java -jar lib/ace.jar db:repair

This command rebuilds the database indexes. If that does not work, you may need to restore a backup. If you have no backup, you can rename the data directory (to keep it for recovery) and let the controller create a fresh one. This will lose all your settings, so only do this as a last resort.

3. Fix Java Issues

On Linux, the controller often relies on the system Java. Check your Java version with java -version. The UniFi Network Application requires Java 8 or 11 (depending on the version). If you have Java 17 or higher, the controller may fail. Install an appropriate version, or set JAVA_HOME to point to the correct one. On Windows and macOS, the controller bundles its own Java, so this is less common, but you can try reinstalling the controller to refresh the bundled Java.

4. Free Disk Space and Fix Permissions

Ensure you have at least 1 GB of free disk space. On Linux, check the data directory permissions: sudo chown -R unifi:unifi /usr/lib/unifi (or wherever your data directory is). On Windows, right-click the UniFi folder and ensure the service account has full control.

5. Reinstall the Controller

If nothing else works, uninstall the controller completely (back up your data directory first) and reinstall the latest version. This is the nuclear option, but it often resolves stubborn issues.

What to Do After the Controller Starts

Once the controller is running, log in to the web UI (https://localhost:8443) and verify that all your devices are connected. If some devices show as disconnected, they may need to be adopted again. Go to the Devices tab and click “Adopt” for any device that is not managed. Also, check that your network settings are intact.

Preventing Future Startup Failures

To avoid this happening again, consider these practices:

• Always shut down the controller gracefully via the web UI or service unifi stop before powering off your machine.
• Keep the controller and your devices on the same firmware major version.
• Back up your controller settings regularly (Settings → System → Backup).
• If you run the controller on a server, allocate at least 2 GB of RAM to the Java process.

Frequently Asked Questions

Why does the UniFi controller fail to start after a Windows update?

Windows updates can change Java environment variables or block ports. Check the logs for port conflicts, and reinstall the controller if necessary. Also ensure that your antivirus is not quarantining the UniFi service.

Can I run the UniFi controller on a Raspberry Pi?

Yes, but it is not officially supported. The controller requires Java and MongoDB, which can run on a Pi, but performance may be slow with many devices. Use a Pi 4 or newer with at least 2 GB RAM.

How do I change the UniFi controller port?

Edit the system.properties file in the UniFi data directory. For example, add unifi.http.port=8081 and unifi.https.port=8444. Then restart the controller. You will need to access the web UI at the new HTTPS port.

What is the default UniFi controller username and password?

There is no default password. The first time you run the controller, you create an administrator account. If you forgot it, you can reset it by stopping the controller and running java -jar lib/ace.jar set-inform (this resets the admin password to “admin” and the username to “admin” on some versions, but it is safer to restore from backup or reinstall).

Why does the controller start but the web UI is not loading?

Check that the Java process is still running and that port 8443 is listening. Try accessing the UI via https://localhost:8443 instead of http://. If you changed the port, use the new one. Also clear your browser cache.

Can I run the UniFi controller in Docker?

Yes, there are community Docker images, but they are not officially supported. If you use Docker, ensure you map the necessary ports (8080, 8443, 8843) and persist the data directory. Startup failures in Docker are usually due to port conflicts or volume permissions.

Related

• Install TWRP on Moto G5 Plus: Full Guide
• AI Automation vs Job Augmentation: What to Know
• Honor 400 Pro Key Specs & Battery Differences