MongoDB upgrade blocks startup unless featureCompatibilityVersion is migrated from 7.0 to 8.0

[cflev]

What happened?

When upgrading persistent data from MongoDB 7.x to 8.2 in LibreChat docker-compose setup, the MongoDB container fails to start if the featureCompatibilityVersion (FCV) was left at 7.0.

Root cause

• MongoDB 8.x requires persistent data to have featureCompatibilityVersion set to 8.0.
• If the FCV is still 7.0 after upgrading the Docker image to 8.x, MongoDB refuses to start, producing a fatal error and entering a restart loop.

Solution/Workaround

1. Roll back to MongoDB 8.0 container.
2. Run: db.adminCommand({ setFeatureCompatibilityVersion: "8.0" }) inside mongosh.
   • On recent MongoDB versions, this may require: db.adminCommand({ setFeatureCompatibilityVersion: "8.0", confirm:true }) (with the correct boolean type).
3. After FCV is migrated to 8.0, update the docker-compose.yml to use MongoDB 8.x (e.g., 8.2). Now the container will start successfully.

Improvement suggestion

Add a migration tip, warning, or upgrade procedure to the documentation and changelog to guide users through FCV update before upgrading MongoDB major versions.

Steps to reproduce

• Start LibreChat with MongoDB 8.0 persistent data
• Stop container, upgrade mongo image to 8.2
• Attempt to start MongoDB 8.x with FCV 7.0
• Observe container not starting, fatal error in logs
• Downgrade to 8.0, update FCV, then upgrade again

Version info

LibreChat: docker-compose setup
MongoDB: upgrade from 7.0 to 8.x

Relevant log output

(Include fatal error due to FCV mismatch)

Comments

This issue supersedes previous focus on the confirm:true parameter; main blocker is the FCV incompatibility, not command syntax.

[cflev]

The main problem is that after upgrading MongoDB from 8.0 to 8.2, if the featureCompatibilityVersion was left at 7.0, the MongoDB container refused to start. The process required starting with MongoDB 7.x, updating the FCV to 8.0, then switching to 8.2 for a successful start.

The confirm:true parameter became relevant only during the FCV upgrade command in 8.x, but the root cause was the version mismatch preventing MongoDB 8.2 from starting with the older FCV.

[jgdub]

I can confirm. I had to modify docker-compose.override.yml to hold mongodb to 8.0 to get things working again.

[michnovka]

For people with docker setup here is a step by step:

1. edit docker-compose.override.yml to pull image with version 8.0

  mongodb:
    image: mongo:8.0

Then restart docker compose

docker compose down
docker compose up -d

2. check that you have v7 feature compatibility:

$ docker exec -it librechat-mongodb mongosh --eval "db.adminCommand({ getParameter: 1, featureCompatibilityVersion: 1 })"
{ featureCompatibilityVersion: { version: '7.0' }, ok: 1 }

3. jump into mongo console:

docker exec -it librechat-mongodb mongosh

Then run upgrade command:

test> db.adminCommand({ setFeatureCompatibilityVersion: "8.0", confirm: true })
{ ok: 1 }

And exit the shell

3. verify this worked:

$ docker exec -it librechat-mongodb mongosh --eval "db.adminCommand({ getParameter: 1, featureCompatibilityVersion: 1 })"
{ featureCompatibilityVersion: { version: '8.0' }, ok: 1 }

4. update docker-compose.override.yml - remove the explicit 8.0 image tag

5. pull and restart docker:

docker compose down
docker compose up -d

6. verify all works:

$ docker exec -it librechat-mongodb mongosh --eval "db.version()"
8.2.1
$ docker exec -it librechat-mongodb mongosh --eval "db.adminCommand({ getParameter: 1, featureCompatibilityVersion: 1 })"
{ featureCompatibilityVersion: { version: '8.0' }, ok: 1 }

[aaronblair]

This resolved the issue for me. Great write up.

[jgdub]

Just got around to doing this on mine and was flawless. Been running pinned to 8.0 for the last few weeks.

Thanks michnovka!

[eshack94]

@michnovka Thank you so much for this. Saved me a lot of time and hassle.

[dareima]

@michnovka this worked great for me as well, thanks so much. Would you or anyone have any idea why this process was necessary on only one of my two LibreChat Docker instances that I upgraded to 0.8.1-rc1 this week?

One upgraded from 0.8.0 just fine without me having to do that, while the other one didn't and where the process you've described was required to make the mongodb container start sucessfully again.

[djuillard]

Thanks a lot

[Korri]

I had the opposite issue, #11151 downgraded my mongodb instance from 8.2 to 8.0, causing the boot to fail with:

Wrong mongod version","attr":{"error":"UPGRADE PROBLEM: Found an invalid featureCompatibilityVersion document (ERROR: Location4926900: Invalid featureCompatibilityVersion document in admin.system.version: { _id: \"featureCompatibilityVersion\", version: \"8.2\" }. See https://docs.mongodb.com/master/release-notes/7.0-compatibility/#feature-compatibility. :: caused by :: Invalid feature compatibility version value '8.2'; expected '7.0' or '7.3' or '8.0'. See https://docs.mongodb.com/master/release-notes/7.0-compatibility/#feature-compatibility.). If the current featureCompatibilityVersion is below 7.0, see the documentation on upgrading at https://docs.mongodb.com/master/release-notes/7.0/#upgrade-procedures.

I had to use docker-compose.override.yml to force mongo:8.2 again.