Cómo solucionar el error ERR_CONNECTION

El error ERR_CONNECTION_REFUSED en localhost indica que tu navegador intenta comunicarse con una dirección local, pero el sistema rechaza activamente la conexión porque ningún proceso está escuchando en ese puerto. La causa más habitual es que el servidor de desarrollo local no se ha iniciado o se está ejecutando en un puerto diferente al que intentas acceder.

Qué significa el error

El mensaje exacto que muestra el navegador suele ser Este sitio no puede alcanzarse o Conexión rechazada, acompañado del código ERR_CONNECTION_REFUSED. Aparece en Google Chrome, Microsoft Edge, Brave y otros navegadores basados en Chromium cuando intentas cargar una URL como http://localhost:3000 o http://127.0.0.1:8080. Afecta directamente a desarrolladores web que trabajan con entornos locales como Node.js, PHP, Python, Docker o herramientas de compilación como Vite y Webpack, impidiéndoles visualizar los cambios en tiempo real.

Causas más habituales

El servidor de desarrollo local está apagado o se ha detenido de forma inesperada.
El puerto configurado en la aplicación no coincide con el puerto que introduces en el navegador.
Existe otra instancia de la misma aplicación bloqueando el puerto de red.
El archivo hosts del sistema operativo redirige mal las peticiones a la dirección local.
Un software de seguridad o cortafuegos bloquea las conexiones internas de red.
El contenedor de Docker que aloja la aplicación no se encuentra en ejecución.

Antes de empezar

Para seguir este procedimiento con seguridad, asegúrate de contar con permisos de administrador en tu sistema operativo (Windows 10 o 11, macOS 14 o distribuciones Linux como Ubuntu 24.04). Guarda los cambios en tus archivos de código fuente antes de reiniciar cualquier servicio de red o terminal para evitar la pérdida de datos temporales en memoria.

Comprobar y reiniciar el servidor de desarrollo

La solución más directa consiste en verificar si el proceso del servidor local sigue activo en tu terminal de comandos. Muchas veces la consola se ha cerrado por error o ha sufrido un fallo interno.

Abre la terminal o línea de comandos donde sueles arrancar tu aplicación local.
Comprueba si ves mensajes de error recientes que indiquen una detención imprevista del proceso.
Detén cualquier comando activo pulsando las teclas Ctrl + C en el teclado.
Vuelve a iniciar el servidor ejecutando el comando correspondiente, por ejemplo
```
npm run dev
```
o
```
php artisan serve
```
.
Espera a que la consola confirme que el servidor está escuchando en un puerto específico.
Abre de nuevo el navegador y accede a la URL exacta que indica la terminal.

Este paso funciona porque reinicia el socket de red y vuelve a abrir el puerto de escucha necesario para aceptar peticiones HTTP desde tu navegador.

Verificar el número de puerto y la URL

Es muy común cambiar de proyecto y mantener abierta una pestaña con el puerto antiguo, o confundir el puerto predeterminado de herramientas como React, Vite o servidores backend.

Revisa el archivo de configuración de tu proyecto, como package.json o vite.config.js.
Identifica la línea donde se define el puerto de escucha, por ejemplo el puerto 3000 o 5173.
Comprueba la barra de direcciones de tu navegador para confirmar que coincide dígito a dígito.
Prueba a cambiar explícitamente al protocolo IP numérico escribiendo http://127.0.0.1:[puerto] en lugar de la palabra localhost.
Limpia la caché del navegador pulsando Ctrl + F5 para forzar la recarga completa sin datos antiguos.

Este paso funciona porque elimina las discrepancias de direccionamiento y fuerza al navegador a buscar la IP interna estándar del adaptador de bucle local.

Liberar el puerto ocupado por otro proceso

Si el sistema operativo indica que el puerto ya está en uso, significa que una instancia fantasma de tu aplicación sigue ejecutándose en segundo plano y bloquea la nueva conexión.

Abre la terminal con privilegios de administrador.
Ejecuta el comando para listar procesos en Windows con
```
netstat -ano | findstr :[puerto]
```
o en Linux/macOS con
```
lsof -i :[puerto]
```
.
Anota el identificador numérico del proceso o PID que aparece al final de la línea activa.
Mata el proceso rebelde en Windows usando
```
taskkill /F /PID [numero_pid]
```
o en sistemas Unix con
```
kill -9 [numero_pid]
```
.
Comprueba que el puerto ha quedado libre repitiendo el comando de comprobación anterior.
Inicia tu servidor de desarrollo local con normalidad.

Este paso funciona porque elimina el bloqueo a nivel de sistema operativo, permitiendo que tu nueva instancia tome el control del puerto de red asignado.

Revisar la configuración de Docker y contenedores

Si desarrollas dentro de contenedores, el error aparece cuando el mapeo de puertos entre tu máquina anfitriona y el entorno virtualizado se ha roto o el contenedor está detenido.

Abre la aplicación de escritorio de Docker o tu terminal habitual.
Ejecuta el comando
```
docker ps -a
```
para listar todos los contenedores disponibles.
Comprueba si el contenedor de tu proyecto figura con estado de encendido o apagado.
Inicia el contenedor ejecutando
```
docker start [nombre_contenedor]
```
o levanta el entorno completo con
```
docker compose up -d
```
.
Revisa el archivo docker-compose.yml para verificar que los puertos están bien mapeados, por ejemplo ports: - "8080:80".
Vuelve a probar la conexión en tu navegador web.

Este paso funciona porque restablece el puente de red virtual que redirige el tráfico desde tu navegador hacia el entorno aislado donde corre la aplicación.

Cómo comprobar que se ha solucionado

Para confirmar que el problema está resuelto de forma definitiva, abre una ventana de incógnito en tu navegador para evitar interferencias de extensiones o cachés persistentes. Introduce la URL local de tu proyecto y comprueba que la interfaz carga correctamente sin demoras. También puedes ejecutar una petición rápida desde la terminal utilizando herramientas de línea de comandos como curl escribiendo

curl -I http://localhost:[puerto]

y verificando que obtienes una respuesta con código de estado HTTP 200 OK o similar.

Si nada de lo anterior funciona

Si el error persiste tras revisar puertos, procesos y contenedores, el problema suele residir en una corrupción profunda de la pila de red de tu sistema operativo o en restricciones de software antivirus de terceros. Revisa los archivos de registro o logs de error específicos de tu entorno de desarrollo para descartar fallos de sintaxis en el arranque de la aplicación. Si utilizas herramientas avanzadas de red o VPN corporativas, desactívalas temporalmente ya que suelen modificar las tablas de enrutamiento local impidiendo el tráfico hacia el bucle local o localhost.

Preguntas frecuentes

¿Por qué funciona en un ordenador y en el mío da error de conexión?

Cada entorno local es independiente. Si clonar un repositorio no viene acompañado de la misma configuración de puertos o dependencias instaladas, el servidor no arrancará y el navegador rechazará la conexión de forma sistemática.

¿Puedo cambiar el puerto por defecto de mi aplicación?

Sí, casi todos los frameworks modernos permiten definir una variable de entorno como PORT en un archivo de configuración o archivo .env para asignar un número de puerto alternativo que no entre en conflicto con otros servicios.

¿Afecta el archivo hosts de Windows o Mac a este error?

Sí, si en algún momento modificaste el archivo hosts para redirigir localhost hacia una dirección IP externa o incorrecta, el sistema no sabrá resolver la ruta interna y devolverá este fallo de conexión de red.