Update MongoDB to 8.x

Upgrading MongoDB from 4.4 to 8.x in Docker

A practical guide for upgrading MongoDB from 4.4 to 8.x using Docker Compose, including all the gotchas you'll likely run into.

---

Overview

You cannot jump directly from 4.4 to 8.x. MongoDB requires stepping through each major version sequentially, setting the Feature Compatibility Version (FCV) at each step before moving on.

Required upgrade path:

4.4 → 5.0 → 6.0 → 7.0 → 8.0 → 8.2

---

Before You Start

1. Back up your data

docker exec <container> mongodump --out /dump
docker cp <container>:/dump ./mongo-backup

2. Check your current FCV

docker exec <container> mongo --eval "db.adminCommand({ getParameter: 1, featureCompatibilityVersion: 1 })"

It should report 4.4.

3. Check AVX support (important!)

MongoDB 5.0+ requires AVX CPU support. Check if your system has it:

grep avx /proc/cpuinfo | head -1

If this returns nothing, see the AVX support section below before continuing.

---

AVX Support

MongoDB 5.0 and above require AVX instructions. If your CPU doesn't expose AVX, the container will fail to start.

Running on a VM (Proxmox, KVM, etc.)?

This is the most common cause. By default, hypervisors present a generic CPU to guests that doesn't include AVX, even if the underlying hardware supports it.

Fix for Proxmox:

1. Shut down the VM from Proxmox (not just the guest OS)
2. Go to your VM → Hardware → Processors
3. Change the CPU Type from kvm64 to one of:
   • host — passes through all host CPU features; best performance but prevents live migration between nodes with different CPUs
   • x86-64-v3 — includes AVX/AVX2, works on most hardware since ~2013, safer for multi-node setups
4. Start the VM and verify:

grep avx /proc/cpuinfo | head -1

You should now see a line of CPU flags including avx.

Bare metal with no AVX?

If you're genuinely on old hardware without AVX, you cannot run MongoDB 5.0+. Your options are:

• Upgrade the hardware
• Use a managed service like MongoDB Atlas
• Consider a MongoDB-compatible alternative like FerretDB

---

The Upgrade Process

The pattern for each version step is:

1. Set FCV on the currently running version
2. Update the image tag in your compose file
3. Bring the container back up
4. Verify it started

Step 1: 4.4 → 5.0

Note: MongoDB 4.4 uses the legacy mongo shell. From 5.0 onwards, use mongosh.

# Set FCV on running 4.4 instance
docker exec <container> mongo --eval 'db.adminCommand({ setFeatureCompatibilityVersion: "4.4" })'

Update your docker-compose.yml:

image: docker.io/library/mongo:5.0

docker compose down
docker compose up -d

# Set FCV to 5.0
docker exec <container> mongosh --eval 'db.adminCommand({ setFeatureCompatibilityVersion: "5.0" })'

---

Step 2: 5.0 → 6.0

# Set FCV on running 5.0 instance
docker exec <container> mongosh --eval 'db.adminCommand({ setFeatureCompatibilityVersion: "5.0" })'

Update your docker-compose.yml:

image: docker.io/library/mongo:6.0

docker compose down
docker compose up -d

docker exec <container> mongosh --eval 'db.adminCommand({ setFeatureCompatibilityVersion: "6.0" })'

---

Step 3: 6.0 → 7.0

docker exec <container> mongosh --eval 'db.adminCommand({ setFeatureCompatibilityVersion: "6.0" })'

Update your docker-compose.yml:

image: docker.io/library/mongo:7.0

docker compose down
docker compose up -d

docker exec <container> mongosh --eval 'db.adminCommand({ setFeatureCompatibilityVersion: "7.0" })'

---

Step 4: 7.0 → 8.0

Note: From 7.0 onwards, MongoDB requires a confirm: true flag when setting FCV because the upgrade is irreversible without support assistance.

docker exec <container> mongosh --eval 'db.adminCommand({ setFeatureCompatibilityVersion: "7.0", confirm: true })'

Update your docker-compose.yml:

image: docker.io/library/mongo:8.0

docker compose down
docker compose up -d

docker exec <container> mongosh --eval 'db.adminCommand({ setFeatureCompatibilityVersion: "8.0", confirm: true })'

---

Step 5: 8.0 → 8.2 (latest)

# Already on 8.0 with FCV set above

Update your docker-compose.yml:

image: docker.io/library/mongo:8.2

docker compose down
docker compose up -d

docker exec <container> mongosh --eval 'db.adminCommand({ setFeatureCompatibilityVersion: "8.2", confirm: true })'

You're done! 🎉

---

Healthcheck

If you have a healthcheck in your compose file, note that the mongo shell was removed in MongoDB 6.0. Update your healthcheck to use mongosh:

healthcheck:
  test: ["CMD-SHELL", "mongosh --eval 'db.runCommand({ping:1}).ok' --quiet"]
  interval: 15s
  timeout: 30s
  retries: 5
  start_period: 35s

---

Troubleshooting

Container fails to start / exit code 62

This usually means FCV mismatch — you skipped setting the FCV before jumping to the next version. Drop back one version, set the FCV, then try again.

docker inspect <container> | grep ExitCode

Check the logs:

docker logs <container>

Look for a line like:

Invalid featureCompatibilityVersion value '7.0'. Expected one of the following versions: '8.2', '8.1', '8.0'

This tells you exactly what went wrong and what version the FCV needs to be at.

docker logs not working

If your logging driver is set to journald, syslog, or none, docker logs won't work. Temporarily change it in your compose file for debugging:

logging:
  driver: json-file

Remember to change it back afterwards.

Can't see logs at all

Try journald directly:

journalctl -u docker --since "10 minutes ago"

---

Key Rules to Remember

• Never skip versions — jumping from 4.4 to 6.0+ will prevent MongoDB from opening your data files
• Always set FCV before upgrading — this is the most common mistake
• mongo shell is gone from 6.0+ — use mongosh instead
• confirm: true is required from the 7.0 → 8.0 FCV step onwards
• Pin your image tag — use mongo:8.2 instead of mongo:8 so a docker compose pull doesn't silently upgrade you to a future minor version