Cómo preparar tu n8n autoalojado para n8n 3.0

n8n 3.0 todavía no se ha publicado: la página de cambios incompatibles de n8n la da como prevista para octubre de 2026, y a 16 de septiembre la versión estable es la 2.39.6. Lo que sí puedes hacer ya es preparar tu instalación para que el día de la actualización no te pille nada por sorpresa. En esta guía abro el informe de migración que trae la 2.39.6, corrijo cada aviso en una instancia con PostgreSQL, hago una copia y arranco sobre ella la imagen v3-nightly, que es una vista previa y no la versión final. Lo probé el 16 de septiembre de 2026 en una máquina arm64 de 18 núcleos con Docker Engine 29.5.2.

Puntos clave

• n8n 3.0 no está publicada. La 2.39.6 es la estable (latest y stable en Docker Hub), la 2.40.1 es la beta y en npm no hay ninguna versión 3.x.
• La 2.39.6 ya evalúa tu instancia contra la 3.0 en Settings > Migration Report. Su cabecera resta un flujo por cada regla que incumple: la mía decía 1 de 7 compatibles cuando eran 3 de 7.
• Lo que más rompe en una instalación con Docker: 37 tipos de nodo que desaparecen, el límite de 60 s del nodo Code, el paso de binaryData a storage y el rango 100.64.0.0/10 si activaste la protección SSRF.
• Un arranque fallido de la nightly ya aplicó 7 migraciones y borró dos tablas, y después la 2.39.6 arrancó sobre esa base sin quejarse. La vuelta atrás sale del volcado, no de cambiar la etiqueta.
• La nightly del 16 de septiembre se identifica como 2.39.0 y aún no bloquea 100.64.0.0/10. Úsala sobre una copia y no la tomes por la 3.0.

¿Qué versión tienes y qué cambia en n8n 3.0?

La 3.0 es una versión de limpieza: quita nodos, endurece valores por defecto y deja la imagen de Docker como única forma de instalar. La guía para desarrolladores del repositorio de n8n lo resume así: "v3 is an operational release: breaking changes, removals, and legacy cleanup". Esa misma guía explica que la rama 3.x es la rama principal más los cambios incompatibles y que se sincroniza a diario. Sus imágenes v3-nightly y v3-rc sirven para probar, con un aviso claro: "Do not use them in production".

A 16 de septiembre de 2026, la página de instalación con Docker^[1] da la 2.39.6 como stable y la 2.40.1 como beta. En Docker Hub, latest y stable apuntan a la misma imagen de la 2.39.6 (sha256:1eb33706d9bd), y beta y next a la 2.40.1, publicada el mismo día. Comprueba cuál ejecutas tú:

docker compose exec n8n n8n --version

La lista oficial de cambios de la 3.0^[2] es larga. Estos son los que te afectan si autoalojas n8n con Docker, junto a lo que puedes hacer ya en la 2.39.6:

Paso 1: abre el informe de migración de la 2.39.6

El informe ya compara tu instancia con la 3.0: está en Settings > Migration Report y solo lo ven los administradores globales. La documentación del informe^[3] sigue escrita para la 2.0. En la 2.39.6, sin embargo, la cabecera ya habla de la "version 3.0.0".

Para probarlo monté una instancia de la 2.39.6 con PostgreSQL 18 y siete flujos preparados a propósito. Entre todos usan:

• Los nodos Function, Function Item e Item Lists
• Un disparador Cron
• Un AI Agent 1.7 en modo ReAct
• Un Execute Workflow en modo por elemento
• Un nodo Code que espera 75 s
• Una petición HTTP a 100.64.10.10, un contenedor con Python que hace de nodo de una tailnet
• Una conversión a fichero

Así quedó el informe:

La pestaña de flujos marcó 6 reglas: la de los modos retirados del AI Agent como crítica y las otras cinco (Execute Workflow por elemento, Cron, Function, Function Item e Item Lists) como medias. La pestaña de instancia marcó otras 6: SSRF, cambio de directorio y paquetes no verificados como medias, y límites de compresión, tiempo límite del nodo Code e importación desde URL como bajas.

La cabecera dice que solo 1 de los 7 flujos es compatible, pero eran 3. El editor resta al total los flujos afectados de cada regla, así que el flujo con Function, Function Item e Item Lists contó tres veces. La API lo confirma: las 6 reglas señalan 4 flujos distintos.

Si prefieres revisarlo desde un script, el editor usa este punto de acceso de su API interna, que no es la API pública y puede cambiar entre versiones. Necesita la cookie de sesión de un administrador:

curl -s -b cookies.txt \
  "http://localhost:5678/rest/breaking-changes/report?version=v3" \
  | jq -r '.data.report.instanceResults[].ruleId'

El registro de arranque de la 2.39.6 repite parte del informe. Al iniciar imprime un bloque "There are deprecations related to your n8n setup" con una línea por variable afectada:

$ docker compose logs --no-log-prefix n8n \
    | grep -oE '^ - [A-Z0-9_]+' | sort -u
 - N8N_COMPRESSION_NODE_MAX_DECOMPRESSED_SIZE_BYTES
 - N8N_COMPRESSION_NODE_MAX_ZIP_ENTRIES
 - N8N_RUNNERS_MODE
 - N8N_RUNNERS_TASK_TIMEOUT
 - N8N_SSRF_PROTECTION_ENABLED
 - N8N_UNVERIFIED_PACKAGES_ENABLED

N8N_RUNNERS_MODE avisa de que el modo interno de los ejecutores de tareas desaparecerá "in a future version". No figura en la lista de la 3.0 y la nightly lo sigue usando, así que no lo trato como bloqueante.

Paso 2: sustituye los nodos que desaparecen

La 3.0 no carga los nodos retirados, y un flujo publicado que los use deja de responder. En la nightly, el webhook del flujo con Function e Item Lists devolvió un 404 con el mensaje Published version not found for workflow with id "b4p3legacy000001", y el registro mostró Unrecognized node type: n8n-nodes-base.cron.

La lista real es más larga que la de la documentación. El catálogo de nodos que trae cada imagen (types/nodes.json) tiene 565 tipos en la 2.39.6 y 528 en la nightly: faltan 37.

La página de la 3.0 nombra cinco. Las reglas del informe proponen sustituto para 28, entre ellos Interval, Read Binary File, Write Binary File, Read PDF, HTML Extract, iCalendar y el nodo OpenAI antiguo. Seis de esos 28 son nodos de IA para Pinecone, Supabase y almacenes en memoria. Estos son los sustitutos que propone el informe para los de uso general:

El cambio de Function Item a Code afecta al código: el objeto item pasa a ser $json y el nodo debe devolver $input.item. Este es el nodo Code en modo por elemento con el que sustituí el mío:

$json.double = $json.n * 2;
return $input.item;

Tras sustituir los nodos de los 4 flujos afectados, el webhook de prueba devolvió {"n":3,"double":6}, lo mismo que con los nodos antiguos, tanto en la 2.39.6 como en la nightly.

Paso 3: fija las variables cuyo valor por defecto cambia

Cinco valores por defecto cambian en la 3.0, y si los fijas ahora en la 2.39.6 la actualización no te los mueve. Estas son las líneas que añadí al fichero de entorno del servicio (tienes más contexto en la guía de variables de entorno y secretos en Docker Compose):

N8N_RUNNERS_TASK_TIMEOUT=300
N8N_UNVERIFIED_PACKAGES_ENABLED=false
N8N_COMPRESSION_NODE_MAX_DECOMPRESSED_SIZE_BYTES=268435456
N8N_COMPRESSION_NODE_MAX_ZIP_ENTRIES=1000
N8N_SSRF_BLOCKED_IP_RANGES=default,100.64.0.0/10
N8N_SSRF_ALLOWED_IP_RANGES=100.64.10.10/32

N8N_RUNNERS_TASK_TIMEOUT=300 conserva los 5 minutos actuales para el nodo Code. Lo medí con un nodo que espera 75 s:

El error de la nightly en el registro fue Task execution timed out after 60 seconds. Si tus nodos Code no pasan del minuto, puedes adoptar ya el nuevo valor.

Las dos líneas de compresión adoptan los límites nuevos. Si tus archivos superan los 256 MiB o las 1000 entradas, vuelve a los valores antiguos: 2147483648 y 5000. El valor false de N8N_UNVERIFIED_PACKAGES_ENABLED es el de la 3.0, así que déjalo en true solo si usas nodos de la comunidad sin verificar.

Revisa también tres variables que yo no tenía. Si usas N8N_DEFAULT_BINARY_DATA_MODE=default, cámbiala a filesystem, s3, azure o database; sin fijarla, la 2.39.6 ya usa filesystem en modo normal y database en modo cola, según su código. La 3.0 también elimina OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS y deja de leer N8N_DB_PING_TIMEOUT: usa DB_PING_TIMEOUT_MS en su lugar.

Si usas Tailscale o Headscale con la protección SSRF

Este cambio solo te afecta si activaste N8N_SSRF_PROTECTION_ENABLED, que viene desactivada por defecto y existe desde la 2.12.0^[4]. Con la protección activa y la palabra default en la lista de bloqueo, la 3.0 añade 100.64.0.0/10. Es el rango que usan Tailscale y Headscale para las direcciones IPv4 de sus nodos, como indica el fichero de configuración de ejemplo de Headscale^[5].

La nightly no sirve para probar este cambio: tanto la imagen del 16 de septiembre como el código de la rama 3.x de ese día tienen la lista antigua de 15 rangos, sin 100.64.0.0/10. Por eso lo ensayé en la 2.39.6, añadiendo el rango a mano con N8N_SSRF_BLOCKED_IP_RANGES=default,100.64.0.0/10. La petición a 100.64.10.10 falló con un 500 y este detalle en la ejecución:

The target 100.64.10.10 is not allowed. This is a security measure to prevent Server-Side Request Forgery (SSRF). If you need to access internal resources, ask your n8n administrator to allowlist the hostname or IP range in the environment configuration.

Con N8N_SSRF_ALLOWED_IP_RANGES=100.64.10.10/32 la misma petición volvió a dar 200. Permite solo los hosts que llamas, o 100.64.0.0/10 entero si llamas a toda la tailnet, y mantén default en la lista de bloqueo, como pide la documentación de las variables SSRF^[6]. Las direcciones IPv6 de Tailscale (fd7a:115c:a1e0::/48) ya caen dentro de fd00::/8, que la lista actual bloquea; eso no lo probé.

Por qué dos avisos no desaparecen del informe

Tras corregir todo, el informe pasó a 7 de 7 flujos compatibles, pero la pestaña de instancia conservó dos avisos:

La regla SSRF solo comprueba si la protección está activa y si la lista contiene default, así que sigue avisando aunque ya hayas permitido tus hosts. El aviso de importación desde URL es informativo y sale en cualquier instancia. Su enlace "Documentation" lleva a la página general de variables de seguridad, que no incluye las de SSRF.

Paso 4: pasa de binaryData a storage antes que la 3.0

La 3.0 renombra ~/.n8n/binaryData a ~/.n8n/storage en el primer arranque, y en dos casos ese cambio impide arrancar. Mira primero qué tienes dentro del contenedor:

docker compose exec n8n ls /home/node/.n8n

Si ves storage y no binaryData, no tienes nada que hacer: un volumen nuevo creado con la 2.39.6 ya usa storage. Un volumen creado con una versión anterior (lo comprobé con uno de la 2.0.0) tiene binaryData, y la 2.39.6 lo avisa en el registro con will be renamed to "/home/node/.n8n/storage" in n8n v3. To migrate now, set N8N_MIGRATE_FS_STORAGE_PATH=true.

Si binaryData vive dentro del volumen principal, arranca la 2.39.6 una vez con N8N_MIGRATE_FS_STORAGE_PATH=true. En mi prueba renombró el directorio sin escribir nada en el registro y añadió "fsStorageMigrated": true al fichero config del volumen. Al quitar la variable y reiniciar, la 2.39.6 siguió escribiendo en storage y no volvió a crear binaryData.

Si montas un volumen o una carpeta del host directamente en binaryData, como hice en el laboratorio, la nightly se detiene con este error:

Failed to migrate /home/node/.n8n/binaryData to /home/node/.n8n/storage because /home/node/.n8n/binaryData is a mount point. Mount the volume at /home/node/.n8n/storage instead, or set N8N_STORAGE_PATH=/home/node/.n8n/binaryData to keep the current path.

Cambia el destino del montaje en tu compose.yml (la guía de volúmenes y bind mounts explica la diferencia entre ambos):

    volumes:
      - n8n_data:/home/node/.n8n
      - ./binarydata:/home/node/.n8n/storage

Con eso no basta. Docker creó un directorio binaryData vacío dentro del volumen principal para usarlo como punto de montaje, y ese directorio sigue ahí. Con el montaje ya movido, la nightly paró con otro error:

Both /home/node/.n8n/binaryData and /home/node/.n8n/storage exist, so n8n cannot tell which one holds your data. Move the contents of /home/node/.n8n/binaryData into /home/node/.n8n/storage, remove /home/node/.n8n/binaryData, then start n8n again.

Bórralo con el servicio parado. rmdir solo elimina directorios vacíos, así que si falla es que ahí hay datos y tienes que moverlos antes. Sustituye nombre_del_volumen por el que muestra docker volume ls:

docker compose stop n8n
docker run --rm -v nombre_del_volumen:/data alpine:3 \
  rmdir /data/binaryData
docker compose up -d n8n

Después del cambio, la 2.39.6 siguió sirviendo el fichero de 200 015 bytes guardado antes de mover el montaje. Los ficheros nuevos se escribieron en la misma carpeta del host.

Paso 5: copia la instancia y arranca la nightly sobre la copia

Cualquier arranque de una versión más nueva migra la base de datos, así que la nightly solo se prueba sobre una copia. Con el servicio parado, vuelca PostgreSQL y empaqueta el volumen de n8n, que guarda el fichero config con la clave de cifrado de las credenciales si no la defines con N8N_ENCRYPTION_KEY:

docker compose stop n8n
docker compose exec -T postgres pg_dump -U n8n -Fc n8n \
  > n8n-2.39.6.dump
docker run --rm -v nombre_del_volumen:/from:ro \
  -v "$PWD":/to alpine:3 \
  tar -C /from -czf /to/n8n_data-2.39.6.tgz .
tar -C binarydata -czf binarydata-2.39.6.tgz .
docker compose start n8n

En mi instancia de prueba el volcado ocupó 484 KB y tardó 0,4 s, una cifra que solo sirve para esta instancia de juguete.

Restaura la copia en otro proyecto de Compose, con su propio puerto y sus propios volúmenes, y apunta su servicio n8n a la imagen de prueba. La etiqueta v3-nightly cambia cada día; si quieres repetir exactamente mi prueba, fija el digest n8nio/n8n@sha256:80dabb0dc7f691603c8f798df8d1770e47a40d78f40eb09972d4c82871a9729d, o usa una candidata inmutable como v3-rc-20260914.2. Para restaurar la base de datos:

docker compose -p n8n-prueba-v3 up -d --wait postgres
docker compose -p n8n-prueba-v3 exec -T postgres \
  pg_restore -U n8n -d n8n --no-owner < n8n-2.39.6.dump

Esta es la comparación de los cuatro webhooks del laboratorio. La columna central es una copia en la que solo moví el montaje de storage, para que la nightly pudiera arrancar:

Sobre la copia corregida, la nightly aplicó 7 migraciones y /healthz/readiness respondió 200 tras 6,50, 6,66 y 6,81 s en tres restauraciones limpias (mediana de 6,66 s). La carga media de la máquina estaba entre 28 y 30 con 18 núcleos, porque la compartía con otros trabajos.

El registro de la nightly dice Recorded version change: 2.39.6 -> 2.39.0, y n8n --version devuelve 2.39.0. La candidata del 14 de septiembre también se identifica así. Tenlo en cuenta si tu monitorización compara números de versión.

Por qué la vuelta atrás tiene que salir del volcado

Un arranque fallido de la nightly ya había modificado la base de datos. En la primera copia, la nightly se detuvo por el error del punto de montaje, pero antes aplicó 7 migraciones. La tabla migrations pasó de 263 a 270 filas, y una de ellas, DropGitConnectionTables, borró las tablas git_connection y git_connection_project.

Después arranqué la 2.39.6 sobre esa misma base. Arrancó, activó los 5 flujos publicados y no escribió ningún error, pero su esquema ya no era el que ella había creado. Por eso no basta con volver a poner 2.39.6 en la etiqueta: restaura el volcado y el volumen.

docker compose stop n8n
docker compose exec -T postgres psql -U n8n -d postgres \
  -c "drop database n8n with (force)" \
  -c "create database n8n owner n8n"
docker compose exec -T postgres \
  pg_restore -U n8n -d n8n --no-owner < n8n-2.39.6.dump

Vacía el volumen de n8n, descomprime en él n8n_data-2.39.6.tgz, deja la imagen en n8nio/n8n:2.39.6 y arranca. Fija la versión también en producción. La página de la 2.0 avisó de que las etiquetas latest y next desaparecerán en una versión mayor futura. Si actualizas con Watchtower sobre latest, recibirás la 3.0 sin elegirla o te quedarás en una etiqueta que ya no se mueve.

Si todavía ejecutas n8n con npm

La 3.0 solo se podrá ejecutar con la imagen oficial. En npm, latest y stable apuntan a la 2.39.6 y no existe ninguna 3.x, y el package.json de la nightly lleva "private": true, la marca que impide publicar un paquete en npm. La página de n8n promete una guía paso a paso que todavía no ha publicado.

El texto de la regla en la 2.39.6 da el camino: pasar a la imagen oficial antes de actualizar "reusing your existing database and encryption key". El contenedor ejecuta n8n como el usuario node (uid 1000) con los datos en /home/node/.n8n, así que monta ahí tu ~/.n8n con ese propietario, arranca la misma versión que tenías y actualiza después. Yo no probé una instalación con npm. La guía de instalación de n8n con Docker que publicamos en octubre de 2025 es anterior a la 2.0, así que usa la documentación de n8n para la parte de Compose.

Lo que esta prueba no cubre

La prueba se hizo con una nightly, no con la 3.0 final, y la página de n8n avisa de que se actualizará "as n8n 3.0 approaches its release". Tampoco probé estos casos:

• Los rangos IPv6 de transición que la 3.0 añade a la lista SSRF
• El modo cola, donde las ejecuciones manuales pasarán siempre a los workers
• Los ejecutores de tareas en modo externo
• Chat Hub, los paquetes de la comunidad y $getPairedItem
• Una migración real desde npm

Vuelve a abrir el informe tras cada actualización de la 2.x: la 2.39.6 añadió la regla del cambio de directorio, y pueden llegar más antes de octubre. Si al final prefieres cambiar de herramienta, tienes la comparación de Activepieces y Windmill frente a n8n.

Preguntas frecuentes

¿Cuándo sale n8n 3.0?

No hay fecha exacta. La página de cambios incompatibles, consultada el 16 de septiembre de 2026, dice "scheduled for October 2026", y la guía del repositorio habla de "~October 2026".

¿Puedo usar la imagen v3-nightly en producción?

No. La guía del repositorio de n8n lo prohíbe expresamente, la etiqueta cambia cada día y la nightly del 16 de septiembre todavía no incluye el bloqueo de 100.64.0.0/10.

¿El informe de migración detecta todos los problemas?

En mi prueba encontró los 4 flujos afectados, aunque la cabecera los contó como 6. Además, no comprueba si binaryData es un punto de montaje, que es el caso que impide arrancar, y el aviso SSRF sigue ahí aunque ya hayas permitido tus hosts.

Conclusión

La preparación para n8n 3.0 se hace hoy en la 2.39.6: abre el informe, sustituye los nodos retirados, fija los cinco valores que cambian y pasa binaryData a storage. Después ensaya la nightly sobre una copia, que no es opcional, porque un arranque fallido ya migra la base de datos. Guarda el volcado, fija la versión y repite el informe cuando salga la 3.0 final. La versión en inglés de esta guía está en How to prepare your self-hosted n8n for n8n 3.0.

Fuentes

1. página de instalación con Docker
2. lista oficial de cambios de la 3.0
3. documentación del informe
4. desde la 2.12.0
5. fichero de configuración de ejemplo de Headscale
6. documentación de las variables SSRF
7. n8n, guía DEVELOPING_V3.md del repositorio
8. GitHub, versión n8n@2.39.6
9. Docker Hub, imagen n8nio/n8n