From time to time, when I upgrade my standalone Unifi controller (running in FreeBSD jail), I run into an issue which requires some manual action to resolve. The issue manifests as MongoDB (bundled with Unifi controller) refusing to start with existing data. Checking logs (/usr/local/share/java/unifi/logs/mongod.log) I can see the following (this log file is in JSON format - not particularly friendly for humans but still readable):

{"t":{"$date":"2025-02-01T21:39:17.097+00:00"},"s":"F",  "c":"CONTROL",  "id":20573,   "ctx":"initandlisten","msg":"Wrong mongod version","attr":{"error":"UPGRADE PROBLEM: Found an invalid featureCompatibilityVersion document (ERROR: Location4926900: Invalid featureCompatibilityVersion document in admin.system.version: { _id: \"featureCompatibilityVersion\", version: \"4.4\" }. See https://docs.mongodb.com/master/release-notes/5.0-compatibility/#feature-compatibility. :: caused by :: Invalid feature compatibility version value, expected '5.0' or '5.3' or '6.0. See https://docs.mongodb.com/master/release-notes/5.0-compatibility/#feature-compatibility.). If the current featureCompatibilityVersion is below 5.0, see the documentation on upgrading at https://docs.mongodb.com/master/release-notes/5.0/#upgrade-procedures."}}

I'm not very experienced with MongoDB and this message looks rather obscure and scary. Fortunately so far it was fairly easy to fix.

The particular text to look for in the log message is

UPGRADE PROBLEM: Found an invalid featureCompatibilityVersion document.

I believe MongoDB can only handle a certain limited version changes automatically. If the binary bundled with Unifi controller is "too new" then it will refuse to load existing data. Moreover one has to mark the data explicitly by setting a more recent featureCompatibilityVersion - there will be no automated upgrade of this parameter.

I think for MongoDB this is a reasonable approach. However in my case MongoDB is an internal part of Unifi controller and I should not normally need to even know about this implementation detail. So I would expect the controller to handle all such upgrades automatically. Unfortunately this does not seem to happen. As a result I can easily run into this problem even if I did not skip any upgrade steps. Here's an example scenario:

  1. Start from Unifi controller with bundled MongoDB 4.4.
  2. Upgrade to the one which includes 5.0. MongoDB 5.0 will work with data from 4.4 but nothing marks data as upgraded.
  3. Upgrade to the version of controller which comes with MongoDB 6.0. Now MongoDB will refuse to load the data which still have featureCompatibilityVersion set to 4.4.

To resolve the problem I had to

  1. Find a version of MongoDB which would load the data (5.0 in the recent case). Start it with --dbpath /usr/local/share/java/unifi/data/db parameter (should probably also start it as unifi user).
  2. Install mongosh: sudo pkg -j unifi install mongosh
  3. Run mongosh and execute db.adminCommand( { setFeatureCompatibilityVersion: "5.0" } )
  4. Repeat steps 1-3 until reaching current version.