How to Fix a Stuck UniFi Controller Start Sequence (Boot Troubleshooting Guide)

If you've ever run into the dreaded "starting UniFi Controller, " message that just doesn’t seem to go away, you're not alone. Whether you’re self-hosting on a VM, running it on a Cloud Key, or deploying in Docker, a stuck boot can mean trouble. The controller doesn't crash, it doesn't log errors, it just hangs there, eternally "starting". So what's going on?

Let's dive in !!

Before we dive in, please don't self-host your UniFi Controller if you take care of client networks. Sooner or later this will cause issues! It's fine for home users, but definitely not recommended for IT service businesses and MSPs. If you want secure, reliable and a scalable hosting solution check out UniHosted.

Why the UniFi Controller gets stuck on boot

This issue usually hits self-hosted setups more than official UniFi consoles. Here’s why it might happen:

  • The MongoDB instance (which UniFi relies on) isn’t running or is corrupted.
  • Disk space is full.
  • Java version is outdated or incompatible.
  • Configuration files are corrupted.
  • You ran an update and didn’t reboot properly.
  • Permissions on key folders are messed up.

UniFi Network is still a Java app that talks to MongoDB. If either of those pieces breaks or slows down, your controller won’t boot.

First things first: check your logs

Look here:

bash
tail -f /usr/lib/unifi/logs/server.log

You’ll either see:

  • Nothing at all: That means the UniFi app never got far enough to even start.
  • A repetitive line that ends in waiting for mongo to be available: That’s your issue.
  • A loop of “Starting UniFi Controller” messages: It's likely stuck in a bad state.

Step-by-step guide to fixing it

1. Restart the UniFi Controller service

This one’s obvious, but just to cover it:

bash
sudo systemctl restart unifi

Or if you’re running on a non-systemd system:

bash
sudo service unifi restart

Wait 30 seconds and check if it's working. If not, continue.

2. Check MongoDB status

UniFi uses a built-in MongoDB, but if it’s broken, nothing else will load. Run:

bash
ps aux | grep mongo

If you don’t see it running, try this:

bash
sudo systemctl restart mongodb

If your system doesn't use standalone MongoDB (e.g., Docker or older UniFi installs), you might have to kill and restart the internal service:

bash
sudo killall -9 mongod
sudo systemctl restart unifi

3. Free up some disk space

If your disk is full, Mongo won’t start.

bash
df -h

If you're at 100%, clean out logs or old backups:

bash
sudo rm -rf /usr/lib/unifi/logs/*
sudo rm -rf /var/lib/unifi/backup/autobackup/*

Then restart again:

bash
sudo systemctl restart unifi

4. Check Java version

If you updated Java and UniFi is now stuck, it might be using a version it doesn’t like.

Check with:

bash
java -version

UniFi generally works best with OpenJDK 8 or 11. If you're running Java 17 or higher, downgrade or explicitly tell UniFi which one to use.

bash
sudo update-alternatives --config java

Pick Java 8 or 11 from the list.

5. Reset UniFi's internal MongoDB lock

Sometimes Mongo doesn’t shut down cleanly, and a lock file remains. Try this:

bash
sudo rm -f /usr/lib/unifi/data/db/mongod.lock

And then:

bash
sudo mongod --dbpath /usr/lib/unifi/data/db --repair

Restart again:

bash
sudo systemctl start unifi

6. Try a full reboot

If you're running it on a VM or physical box and nothing's helped so far, give it a reboot:

bash
sudo reboot

Yes, the old “have you tried turning it off and on again” trick still works wonders.

7. Reinstall UniFi (as last resort)

Back up your data first:

bash
cp /var/lib/unifi/backup/autobackup /tmp/unifi-backup

Then uninstall UniFi:

bash
sudo apt-get remove unifi

And reinstall:

bash
sudo apt-get update
sudo apt-get install unifi

Place the backups back after reinstall and restore them from the UI.

Docker-specific fixes

If you’re running UniFi in Docker, your container might just be stuck in a bad loop. Try this:

bash
docker restart unifi

If you want to nuke and rebuild:

bash
docker stop unifi
docker rm unifi
docker pull jacobalberty/unifi
docker run -d --name=unifi -v /path/to/data:/unifi -p 8443:8443 jacobalberty/unifi

Make sure your data volume is mapped correctly, or you'll lose everything.

Cloud Key stuck?

If you're using a Cloud Key and it’s stuck:

  1. SSH into it using default credentials (ubnt / ubnt unless changed).
  2. Run:
bash
sudo service unifi restart

Or if it’s a G2 or later:

bash
podman restart unifi

You can also try factory resetting it via the button on the device.

Dream Machine stuck?

Dream Machines run UniFi OS, so the process is different. SSH into it:

bash
ssh root@192.168.1.1

Then:

bash
unifi-os restart

If that fails, try a full reboot:

bash
reboot

Worst case: reset the UDM from the button and restore from backup.

Backups and prevention

Avoiding this issue in the future is half the battle. Here's how:

  • Enable automatic cloud backups via your UI account.
  • Don’t force upgrades, check compatibility first.
  • Monitor disk space.
  • Avoid unnecessary Java upgrades.
  • Don’t run UniFi alongside other services on the same box.

If your setup is critical, it's worth looking at running your controller somewhere more stable.

Final thoughts

A stuck UniFi Controller can ruin your day, especially if you manage client networks. But with a bit of patience (and log reading), it’s almost always recoverable.

And really, if this stuff is happening too often, maybe it’s time to stop self-hosting. That’s exactly why we built Unihosted, to run your controller reliably in the cloud, with daily backups, tested updates, and all the scaling you could want.