El error UPGRADE PROBLEM: Found an invalid featureCompatibilityVersion document significa que un mongod 9.0 ha encontrado datos guardados con una versión de compatibilidad que no sabe abrir, y se arregla subiendo por pasos, no borrando el volumen. La etiqueta mongo:latest de Docker Hub apunta a MongoDB 9.0 desde el 1 de octubre de 2026, y la 9.0 solo acepta datos con la featureCompatibilityVersion (FCV, la versión de compatibilidad de funciones) en 8.0 u 8.3. Si tus datos están en 8.2 o siguen en 7.0, el contenedor se reinicia en bucle con el código 62. Lo reproduje el 27 de octubre de 2026 en Linux arm64 con Docker 29.5.2, Compose v2.40.3 y las imágenes mongo:8.2 (8.2.12), mongo:8.3 (8.3.13) y mongo:latest (9.0.4). Tienes la versión en inglés de esta guía.

Puntos clave

  • mongo:latest, mongo:9 y mongo:9.0 son hoy la misma imagen, MongoDB 9.0.4; mongo:8 es la 8.3.13.
  • MongoDB 9.0 solo arranca sobre datos con la FCV en 9.0, 8.3 u 8.0. Con 8.2 o 7.0 el proceso termina con el código 62.
  • Volver a la imagen anterior arregla el arranque al momento: el intento fallido de la 9.0 no toca los datos.
  • La ruta segura desde 8.2 es mongo:8.3, setFeatureCompatibilityVersion: "8.3", mongo:9.0 y setFeatureCompatibilityVersion: "9.0", todo con confirm: true.
  • El compose oficial de Komodo usa image: mongo sin etiqueta, así que también le afecta.

¿Qué significa UPGRADE PROBLEM: Found an invalid featureCompatibilityVersion document?

Significa que el binario de mongod es demasiado nuevo para la FCV que guardan tus datos. MongoDB anota esa versión en la colección admin.system.version, y cada binario solo abre un puñado de valores. Este es el mensaje fatal que dejó mi contenedor con mongo:latest sobre datos creados con la 8.2, partido en diez líneas para que quepa:

"s":"F", "c":"CONTROL", "id":20573, "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: \"8.2\" }. [...]
:: caused by :: Invalid feature compatibility version value '8.2'.
Expected one of the following versions: ''9.0', '8.3', '8.0'. [...]
If the current featureCompatibilityVersion is below 8.0, see the
documentation on upgrading at https://docs.mongodb.com/master/
release-notes/8.0/#upgrade-procedures."}}

La última frase despista, porque habla de versiones por debajo de la 8.0 aunque tus datos estén en 8.2. La pista útil es la lista Expected one of the following versions: son las FCV que acepta el binario. Después del error, mongod registra Shutting down con exitCode 62 y Docker lo reinicia. En mis pruebas, docker inspect mostraba restarting 62 y ocho reinicios en los primeros 15 segundos.

¿Por qué ha empezado a fallar ahora?

Ha empezado a fallar porque la etiqueta que usas cambió de versión mayor sin que tú hicieras nada. MongoDB publicó la 9.0 el 29 de septiembre de 2026, y la imagen oficial la añadió al día siguiente con el cambio 771 de docker-library/mongo[1]. Desde el 1 de octubre, latest apunta a la 9.0, como anotó el autor de docker-lmelp en su incidencia 74[2]. El siguiente docker compose pull, o la siguiente pasada de Watchtower, descarga la 9.0 sobre tus datos de siempre.

MongoDB alterna versiones de soporte largo, como la 8.0, con versiones rápidas, como la 8.1, la 8.2 y la 8.3. La guía oficial para subir a 9.0[3] lo deja claro: "To upgrade an existing MongoDB deployment to 9.0, you must be running a 8.3 or 8.0 release." La 8.2 no está en esa lista, y la etiqueta mongo:8.2 no recibe actualizaciones desde el 23 de julio de 2026. Esto es lo que obtuve al arrancar mongo:latest (9.0.4) sobre cada combinación:

  • Datos de mongo:8.0 (FCV 8.0): la 9.0.4 arranca y la FCV se queda en 8.0
  • Datos de mongo:8.2 (FCV 8.2): código 62 con value '8.2'
  • Datos de mongo:7.0 pasados a mongo:8.0 sin cambiar la FCV (FCV 7.0): código 62 con value '7.0'
  • Datos de mongo:8.3 con la FCV subida a 8.3: la 9.0.4 arranca

El tercer caso es la trampa menos visible. Un mongod 8.0 abre datos en FCV 7.0 sin quejarse, así que puedes llevar meses en la 8.0 con la FCV de la 7.0.

Cómo comprobar la FCV de tus datos sin arrancar la 9.0

La FCV solo se consulta con un mongod que arranque, así que primero vuelve a la imagen que funcionaba. Uso este compose, con la etiqueta en una variable para cambiarla desde la línea de comandos:

services:
  mongo:
    image: mongo:${MONGO_TAG:-8.2}
    volumes:
      - mongo-data:/data/db
    ports:
      - "127.0.0.1:32417:27017"
    restart: unless-stopped
volumes:
  mongo-data:

Arranca la versión anterior y pregunta por la FCV. La opción -T de exec evita pedir una terminal, y la puedes quitar si lo ejecutas a mano:

MONGO_TAG=8.2 docker compose up -d
docker compose exec -T mongo mongosh --quiet --eval \
  'db.adminCommand({getParameter: 1, featureCompatibilityVersion: 1})'

La respuesta en mi laboratorio fue featureCompatibilityVersion: { version: '8.2' }, y el recuento de tienda.pedidos seguía en 1000 documentos después del intento con la 9.0. Si no sabes con qué versión creaste los datos, mira el número que devuelve: esa es la versión que manda, no la etiqueta de tu compose.

Arreglo inmediato: fija la etiqueta que abría tus datos

El arreglo de urgencia es cambiar image: mongo o mongo:latest por la etiqueta concreta que usabas antes del fallo. Con mongo:8.2 mi contenedor volvió a arrancar a la primera y con los mismos 1000 documentos. Si tus datos estaban en FCV 8.0, mongo:8.0 sirve igual. Así recuperas el servicio y decides cuándo subir de versión, en lugar de que lo decida una descarga automática.

No borres el volumen ni lo inicialices de nuevo para quitarte el error de encima. El error sale durante el arranque (initandlisten), antes de que mongod acepte conexiones, y la 8.2 abrió los datos sin problema después del fallo.

Cómo pasar de MongoDB 8.2 a 9.0 sin perder datos

La ruta que funciona desde 8.2 tiene cuatro pasos y una parada obligatoria en la 8.3. Haz antes una copia con mongodump, que viene dentro de la imagen oficial (versión 100.20.0 en la 8.3.13):

docker compose exec -T mongo mongodump --archive --gzip \
  > copia-mongo.archive.gz

En mi caso, el archivo de 1000 documentos ocupó 7215 bytes. Después sube a la 8.3, que sí abre datos en FCV 8.2, y cambia la FCV:

MONGO_TAG=8.3 docker compose up -d
docker compose exec -T mongo mongosh --quiet --eval \
  'db.adminCommand({setFeatureCompatibilityVersion: "8.3", confirm: true})'

Sin confirm: true la orden falla con MongoServerError: To proceed with the FCV upgrade, please re-run this command with 'confirm: true'. La respuesta correcta es { ok: 1 }, y getParameter pasa a devolver version: '8.3'.

Con la FCV en 8.3, cambia a la 9.0 y repite la orden con el nuevo valor:

MONGO_TAG=9.0 docker compose up -d
docker compose exec -T mongo mongosh --quiet --eval \
  'db.adminCommand({setFeatureCompatibilityVersion: "9.0", confirm: true})'

mongo:9.0 y mongo:latest comparten hoy el resumen sha256:741da947cd8d, y probé las dos. El contenedor arrancó sin reinicios y siguió con FCV 8.3 hasta que ejecuté la orden. Después db.version() devolvió 9.0.4, la colección seguía con 1000 documentos y la suma del campo total daba 749 250, igual que antes.

Si tus datos siguen en FCV 7.0

Si la consulta devuelve 7.0, el atajo es la 8.0, porque la 9.0 acepta esa FCV de forma directa. Arranca mongo:8.0, ejecuta setFeatureCompatibilityVersion: "8.0" con confirm: true y cambia a la 9.0. Lo probé con datos creados por mongo:7.0 (7.0.45) y pasados a mongo:8.0 (8.0.34) sin tocar la FCV, y la 9.0.4 arrancó a la primera con el documento de prueba.

¿Se puede volver de MongoDB 9.0 a 8.3?

Sí, pero solo si bajas la FCV antes de cambiar la imagen. Con la FCV en 9.0, mongo:8.3 falla con el mismo error al revés: Invalid feature compatibility version value '9.0'. Expected one of the following versions: ''8.3', '8.2', '8.0'. La lista también explica por qué la 8.3 abre los datos de la 8.2.

Para volver, ejecuta en la 9.0 setFeatureCompatibilityVersion: "8.3" con confirm: true y después arranca mongo:8.3. Así lo hice, y la 8.3.13 arrancó con los 1000 documentos y FCV 8.3. Por eso conviene dejar la FCV en 8.3 unos días tras subir a 9.0. Mientras no la cambies, volver atrás es cambiar la etiqueta.

Cómo evitar que vuelva a pasar con la próxima versión

La prevención es no usar mongo ni mongo:latest para una base de datos con datos. Fija la etiqueta de la versión mayor que quieres, como mongo:8.0 o mongo:9.0, y sube de versión cuando tú lo decidas. El 27 de octubre de 2026, el compose de MongoDB del repositorio de Komodo seguía con image: mongo, así que si lo instalaste con la guía de Komodo con Docker, revisa esa línea.

Si actualizas con Watchtower, excluye el contenedor de MongoDB o fija su etiqueta, porque Watchtower descarga lo que diga la etiqueta sin mirar la FCV. Un healthcheck en Docker Compose no evita el fallo, pero cambia un bucle de reinicios silencioso por un contenedor marcado como unhealthy que tu monitorización sí ve.

Preguntas frecuentes

¿Pierdo los datos si la 9.0 ya intentó arrancar?

No en mi prueba. La 9.0 se reinició al menos ocho veces sobre los datos en FCV 8.2, y la 8.2 los abrió después con los 1000 documentos. El error sale en la fase initandlisten del arranque, antes de que mongod acepte conexiones.

¿Puedo saltar directamente de la 8.2 a la 9.0 cambiando la FCV a 9.0?

No. La 8.2 no conoce el valor 9.0, y la 9.0 no abre datos en 8.2, así que la parada en la 8.3 es obligatoria. Desde la 8.0 sí puedes saltar a la 9.0, porque la FCV 8.0 está en la lista de la 9.0.

¿Sirve de algo borrar el contenedor y volver a crearlo?

No, porque la FCV vive en el volumen /data/db, no en el contenedor. Recrearlo con la misma imagen da el mismo error. Solo cambia algo si cambias la imagen o, en el último caso, si restauras una copia de mongodump sobre un volumen nuevo.

Conclusión

UPGRADE PROBLEM: Found an invalid featureCompatibilityVersion document no es corrupción de datos: es una 9.0 que ha llegado por la etiqueta latest a unos datos en FCV 8.2 o 7.0. Vuelve a la etiqueta anterior para recuperar el servicio y haz una copia con mongodump. Después sube por la 8.3, o por la 8.0 si vienes de la 7.0, con confirm: true en cada paso. Guarda esa copia también en otra máquina, por ejemplo con restic, antes de tocar la FCV en producción.

Fuentes: [1] MongoDB, Upgrade 8.3 Standalone to 9.0[3], [2] MongoDB, Upgrade 8.3 to 9.0[4], [3] MongoDB Community, MongoDB 9.0 is Now Available[5], [4] docker-library/mongo, cambio 771 que añade la 9.0[1], [5] Docker Hub, imagen oficial mongo[6], [6] stoatchat/self-hosted, incidencia 312 con el mismo error[7], [7] Komodo, compose con MongoDB[8], [8] castorfou/docker-lmelp, incidencia 74[2].

Fuentes

  1. cambio 771 de docker-library/mongo
  2. docker-lmelp en su incidencia 74
  3. guía oficial para subir a 9.0
  4. MongoDB, Upgrade 8.3 to 9.0
  5. MongoDB Community, MongoDB 9.0 is Now Available
  6. Docker Hub, imagen oficial mongo
  7. stoatchat/self-hosted, incidencia 312 con el mismo error
  8. Komodo, compose con MongoDB