n8n no arranca tras una actualización: causas y rollback

Una actualización de n8n se completa, el contenedor se reinicia y después la pantalla de inicio de sesión queda en blanco o los registros solo muestran mensajes de error. Para una instancia en producción que envía facturas, reparte leads o clasifica tickets de soporte, esto no es un problema menor, sino una auténtica emergencia. Cada empleado digital que se ejecuta en esa instancia se detiene por completo en ese momento.

La buena noticia: en la gran mayoría de los casos se puede acotar la interrupción en pocos minutos si actúas de forma sistemática en lugar de tocar ajustes al azar. Este artículo ordena las causas más frecuentes cuando n8n no arranca tras una actualización, te ofrece una checklist de emergencia y el camino de vuelta a una versión fijada y funcional. Así mantienes el control de tus automatizaciones, incluso si una actualización sale mal.

Las causas más frecuentes cuando n8n no arranca tras la actualización

Migración de base de datos fallida

En cada salto de versión, n8n ejecuta automáticamente al iniciar migraciones de base de datos que adaptan el esquema a la nueva versión. Si una de estas migraciones falla, la instancia queda atrapada en un bucle de arranque y los registros muestran un mensaje como "There was an error running database migrations". Los hilos del foro de n8n indican que esto ocurre sobre todo cuando se saltan varias versiones de golpe, cuando la base de datos subyacente funciona en una versión que ya no está soportada, o cuando un único paso de migración contenía un error que solo se corrigió en un parche posterior. Precisamente por eso, la guía oficial de actualización de n8n recomienda actualizar con regularidad y no saltarse demasiadas versiones a la vez, ya que esto reduce notablemente el riesgo de problemas de migración.

Versión de Node.js incompatible

n8n define para cada versión un rango de Node.js compatible. Si una instancia gestionada con npm se ejecuta en una versión de Node.js fuera de ese rango, el proceso puede fallar ya en el arranque, sin que exista ningún error real en un workflow. A primera vista, estos mensajes parecen un fallo de n8n, pero en realidad se trata simplemente de un problema de versión del entorno de ejecución.

Clave de cifrado ausente o distinta

Si n8n se ejecuta en modo cola (queue) con varios procesos worker, o si la instancia se volvió a configurar durante la actualización sin conservar la clave de cifrado existente, las credenciales guardadas ya no se podrán descifrar tras el reinicio. La instancia parece entonces arrancar con normalidad, pero determinados workflows fallan de forma reproducible justo en los nodos que necesitan una credencial.

Volúmenes de Docker, permisos y nodos propios

En entornos Docker puede ocurrir que una nueva imagen espere permisos de archivos o directorios distintos en el volumen montado respecto a la versión anterior, o que los community nodes instalados manualmente ya no sean compatibles con la nueva versión de n8n y bloqueen el arranque. Ambos casos suelen mostrarse con mensajes de error claros directamente en los registros del contenedor, en cuanto se buscan específicamente.

Checklist de emergencia: cómo actuar en los primeros minutos

• Guardar los logs de inmediato: obtén con `docker logs <container>` o mediante los archivos de log correspondientes en instalaciones npm el mensaje de error exacto antes de reiniciar nada. Determina si se trata de un problema de migración, de nodo o de permisos.
• Relacionar el mensaje de error con la causa: si el mensaje contiene la palabra "migration", el problema está en la base de datos. Si contiene el nombre de un paquete de un community node, el problema es una extensión incompatible.
• No reiniciar repetidamente: los reinicios múltiples pueden complicar aún más un paso de migración ya iniciado pero no finalizado.
• Comprobar el backup de la base de datos: si existe un backup reciente de la base de datos de n8n, restaurarlo antes del propio rollback de versión suele ser el camino más seguro, especialmente tras una migración fallida.
• Leer las notas de la versión de destino: las notas de la versión de n8n permiten comprobar a posteriori si el salto de actualización incluía cambios importantes conocidos (breaking changes) que coincidan con el mensaje de error.

Rollback a la versión anterior fijada

Si tu instancia se ejecuta con Docker, el rollback suele ser la vía más rápida para volver a un estado funcional. Según la documentación de n8n sobre las opciones de instalación con Docker, la imagen no solo puede referenciarse mediante las etiquetas inestables "latest" o "next", sino fijarse de forma específica a un número de versión concreto, por ejemplo con `docker.n8n.io/n8nio/n8n:1.81.0`. Precisamente ese anclaje (pinning) es también el camino de vuelta: si vuelves a introducir en tu archivo docker-compose o en tu comando de despliegue el último número de versión conocido y funcional, descargas específicamente esa imagen anterior en lugar de la nueva versión fallida.

• Fijar la versión en el archivo compose: sustituye la etiqueta de la imagen por la última versión funcional, por ejemplo `n8nio/n8n:1.80.4` en lugar de `n8nio/n8n:latest`.
• Detener limpiamente el contenedor antiguo: `docker compose down`, para que no siga funcionando en segundo plano ningún proceso a medio iniciar.
• Descargar e iniciar la imagen fijada: `docker compose pull` seguido de `docker compose up -d` obtiene exactamente la versión fijada y reinicia la instancia.
• Tener en cuenta el estado de la base de datos: si una migración ya se ejecutó parcialmente antes de que apareciera el error, un simple downgrade de la imagen puede no ser suficiente. En ese caso, restaurar el backup de la base de datos guardado previamente es la vía más fiable para volver a un estado consistente.
• Instalar una versión concreta en instalaciones npm: mediante la sintaxis de versión, n8n también puede volver a una versión anterior conocida y exacta a través de npm, en lugar de volver a descargar la versión más reciente.

Tras el rollback, merece la pena realizar una breve prueba funcional de los workflows centrales antes de introducir más cambios. Solo cuando la instancia vuelve a funcionar de forma estable llega el momento adecuado para analizar con calma la causa real del error.

Cómo evitar el mismo fallo en la próxima actualización

• Actualizar de forma regular en lugar de esporádica: la documentación de n8n recomienda actualizar al menos una vez al mes, para no tener que saltarse nunca demasiadas versiones de golpe.
• Fijar siempre una versión concreta: evita en producción las etiquetas "latest" o "next" y en su lugar introduce deliberadamente un número de versión concreto, que solo actualizarás tras una prueba satisfactoria.
• Probar en un entorno de pruebas antes de actualizar: aplica primero una actualización en un entorno separado, antes de que afecte a la instancia de producción.
• Hacer un backup antes de cada actualización: un backup reciente de la base de datos justo antes del paso de actualización hace que cualquier rollback sea mucho más sencillo.
• Leer las notas de la versión de antemano: un vistazo rápido a las notas de la versión muestra si la versión de destino trae cambios importantes conocidos (breaking changes) para los que deberías prepararte.

Quien opera una instancia de n8n en producción y desea configurar desde el principio de forma sólida las actualizaciones, los backups y las estrategias de rollback, encuentra apoyo en los servicios de n8n de NordFlux.

Preguntas frecuentes

¿Por qué falla precisamente en mi caso la migración de base de datos durante la actualización?

La causa suele ser que se saltaron varias versiones de golpe, o que la base de datos utilizada funciona en una versión que ya no es compatible correctamente con la nueva versión de n8n. También se producen bugs puntuales en pasos de migración concretos, que luego se corrigen en una versión posterior, por lo que a veces volver a actualizar a la versión más reciente es la solución más sencilla.

¿Basta con volver a iniciar simplemente la antigua imagen de Docker?

En muchos casos sí, sobre todo si el error se produjo justo al arrancar y antes de completarse una migración. Sin embargo, si una migración ya se había ejecutado parcialmente, el esquema de la base de datos puede dejar de coincidir exactamente con la versión anterior. En ese caso, generalmente no hay forma de evitar restaurar un backup de base de datos anterior.

¿Tengo que cambiar algo en la base de datos después de un rollback?

Esto depende de hasta dónde había avanzado la migración fallida. Si la instancia falló ya en el primer paso de migración, a menudo basta con simplemente restablecer la versión. Si, en cambio, ya se habían completado con éxito varios pasos de migración antes de que fallara uno posterior, deberías recurrir a un backup de la base de datos anterior a la actualización para evitar inconsistencias.

¿Cómo evito que n8n se actualice de forma involuntaria al reiniciar?

No utilizando nunca las etiquetas "latest" o "next" en el despliegue, sino fijando un número de versión concreto. Tu instancia solo se actualiza si cambias deliberadamente ese número y has probado previamente la nueva versión.

¿Qué hago si el rollback a la versión anterior tampoco funciona?

Comprueba primero si los registros siguen mostrando el mismo error o si ahora muestran otro distinto. Si el error se mantiene exactamente igual, eso apunta a un backup de base de datos dañado o a un problema ajeno al propio n8n, como permisos faltantes en el volumen. En ese caso, normalmente solo ayuda una restauración limpia de la base de datos a partir de un backup anterior cuyo buen funcionamiento esté comprobado.