Tecnología · GUÍA PRÁCTICA
¿Node EADDRINUSE? Demuestra enlace, escucha y supervisor antes de matar procesos
Conserva dirección y puerto completos, identifica la escucha en el espacio correcto, detén mediante su dueño y verifica un reinicio controlado.
Esta guía trata EADDRINUSE como una auditoría de propiedad del enlace, no como una orden de matar Node. Conserva el objeto de error y acota el conflicto por dirección, familia IP y espacio de red.
Después sigue el PID que escucha hasta la terminal, supervisor, servicio o contenedor que realmente lo administra. Reinicia una sola vez, únicamente tras comprobar que el socket quedó libre, y valida con resultados observables.
1. Congela el fallo de enlace completo
Antes de reiniciar, guarda code, syscall, address, port o la ruta del socket, además del comando real, cwd, versión de Node y supervisor. EADDRINUSE indica que la dirección local está ocupada, no quién la posee.
No reduzcas :::3000 a “puerto 3000 ocupado”. La dirección comodín, la familia IP y el espacio de red forman parte del conflicto.
2. Lee dirección y familia antes que el puerto
Si omites host, Node suele enlazar ::, o 0.0.0.0 sin IPv6. En muchos sistemas el comodín IPv6 también acepta IPv4, por lo que otro enlace IPv4 al mismo puerto puede chocar.
127.0.0.1, 0.0.0.0, ::1 y :: no son equivalentes. No amplíes el enlace ni desactives IPv6 salvo que el diseño lo exija.
3. Inspecciona la escucha en el mismo espacio
En Linux usa ss -ltnp o filtra el puerto exacto. -l significa escucha, -n valores numéricos y -p información del proceso. Eleva privilegios solo lo imprescindible.
En macOS usa lsof; en Windows combina Get-NetTCPConnection y Get-Process. En contenedores inspecciona tanto el puerto publicado del host como el espacio donde falló el proceso.
4. Sigue el PID hasta su dueño real
El PID puede ser un hijo desechable. Registra línea de comandos y padre, y comprueba si nodemon, PM2, systemd, Docker Compose, Kubernetes o el IDE controla su ciclo.
El caso de nodemon muestra choques en :: y 5000 durante un reinicio al guardar. Corrige el ciclo del supervisor y el cierre, no mates todos los procesos Node.
5. Detén mediante el dueño y verifica la liberación
Usa la parada normal del dueño: terminal, aplicación PM2, unidad systemd o contenedor. Reserva la terminación forzada para después de demostrar identidad y alcance.
Repite la inspección. El éxito es que la escucha desaparezca y no reaparezca de inmediato, no solo que el comando termine. Evita killall node y órdenes sudo amplias.
6. Cambia el puerto solo si la arquitectura lo exige
Cambia el puerto solo si dos servicios legítimos necesitan endpoints distintos o el despliegue lo asigna dinámicamente. Saltar de puerto deja supervisores antiguos activos.
Con port 0, lee la dirección real tras listening. Si el puerto fijo pertenece a proxy, firewall, discovery o health check, actualiza todo el contrato.
7. Reinicia una vez y demuestra la escucha
Arranca una sola instancia sin reload ni clúster. Confirma PID o contenedor, dirección local, puerto, familia y una ruta de salud; luego restaura el supervisor.
Si reaparece, compara dueño, padre, espacio y cronología. Tras un socket limpio, la repetición apunta a lanzamiento duplicado o carrera de reinicio, no a caché ni a reinstalar Node.
