Guía 02: Solución al Error ETIMEDOUT en Aplicaciones Node.js (Problema de Resolución IPv6 vs IPv4)
Esta guía documenta la causa y la solución para un problema común y persistente de conectividad de red (errores de “timeout” y “unreachable network”) en entornos basados en Node.js, como el Gateway de OpenClaw, el CLI oficial de Bitwarden o herramientas basadas en npm.
1. El Problema: “El Fantasma de la Red”
Síntomas Comunes
- Aplicaciones que intentan conectarse a servicios externos (APIs, servidores de bases de datos) y fallan silenciosamente o devuelven errores después de un largo tiempo de espera.
- Registros que muestran errores explícitos como:
ETIMEDOUT(Tiempo de espera de conexión agotado)ENETUNREACH(Red inalcanzable)
- En herramientas modernas (Node 22+), advertencias como:
fetch fallback: enabling sticky IPv4-only dispatcher.
La Causa Raíz
El problema no es que la máquina no tenga internet (como lo demuestra una simple prueba con curl), sino cómo el entorno de ejecución (Node.js) resuelve los nombres de dominio (DNS) para encontrar las direcciones IP de los servidores.
Por defecto, las versiones modernas de Node.js intentan conectarse agresivamente utilizando el protocolo IPv6 (registros DNS tipo AAAA) antes de intentar con IPv4 (registros tipo A).
Si el sistema operativo, el enrutador local, o el proveedor de internet del usuario tienen una configuración IPv6 defectuosa, incompleta o bloqueada (lo cual es sorprendentemente común en redes domésticas o VPNs mal configuradas), Node.js intentará conectarse a la dirección IPv6, se quedará esperando una respuesta que nunca llegará, y finalmente agotará el tiempo de espera (timeout), lanzando el error ETIMEDOUT antes de siquiera intentar usar la ruta IPv4 que sí funciona.
2. La Solución: Obligar a Node.js a Preferir IPv4
Para evitar que Node.js pierda tiempo (y falle) intentando conexiones IPv6 rotas, la solución oficial es alterar el comportamiento del motor de resolución DNS a través de variables de entorno.
La Variable Mágica: NODE_OPTIONS
Al establecer la variable de entorno NODE_OPTIONS con el valor --dns-result-order=ipv4first, le indicamos explícitamente a Node.js que, al recibir resultados de una búsqueda DNS, intente conectarse primero a las direcciones IPv4.
NODE_OPTIONS="--dns-result-order=ipv4first"3. Formas de Aplicar la Solución
Existen tres maneras principales de aplicar este parche, dependiendo de cómo se ejecute la aplicación Node.js problemática.
Método A: Para una Ejecución Única en Terminal
Si estás corriendo un comando de una herramienta basada en Node.js (como npm install, bw create item, etc.) y te falla con un timeout, puedes anteponer la variable justo antes del comando.
NODE_OPTIONS="--dns-result-order=ipv4first" comando_a_ejecutarEjemplo real:
NODE_OPTIONS="--dns-result-order=ipv4first" bw login --apikeyMétodo B: Para Toda la Sesión de Terminal Actual
Si vas a correr varios comandos seguidos y no quieres escribir la variable cada vez, puedes “exportarla” para que todos los procesos de Node.js que se lancen en esa ventana de terminal la usen automáticamente.
export NODE_OPTIONS="--dns-result-order=ipv4first"Aviso: Al cerrar la ventana, esta configuración se pierde.
Método C: Para Servicios en Segundo Plano (Systemd)
Si la aplicación es un servicio persistente (como el Gateway de OpenClaw), la variable debe inyectarse en el archivo de configuración del servicio (ej. ~/.config/systemd/user/openclaw-gateway.service).
- Abrir el archivo de servicio con un editor.
- Añadir la siguiente línea en la sección
[Service]:Environment="NODE_OPTIONS=--dns-result-order=ipv4first" - Recargar el demonio de systemd y reiniciar el servicio:
Terminal window systemctl --user daemon-reloadsystemctl --user restart openclaw-gateway.service
(Nota: En casos extremos de redes mal configuradas, como se vio en la Guía 01, ni siquiera este parche funciona si el intermediario de DNS local como systemd-resolved está completamente roto, requiriendo un bypass del DNS del sistema como solución definitiva).