¿ngrok dice que ya hay un túnel corriendo (ERR_NGROK_108 / ERR_NGROK_334)? Así se soluciona

Corres ngrok http 3000 y en vez de una URL de túnel, te aparece:

ERROR: authentication failed: Your account is limited to 1 simultaneous ngrok agent session.
ERR_NGROK_108

O:

ERROR: The tunnel session ... is already bound to another tunnel session.
ERR_NGROK_334

En pantalla no se ve nada raro, ninguna ventana de terminal con un túnel activo, y sin embargo ngrok insiste en que ya hay uno corriendo. Casi siempre es cierto, solo que no está donde estás mirando.

Qué significan realmente estos errores

Ambos vienen de la misma causa: el free tier de ngrok permite exactamente una sesión de agente activa a la vez. ERR_NGROK_108 es el mensaje de límite a nivel de cuenta. ERR_NGROK_334 es la versión de colisión de túnel del mismo problema. Si ayer corriste ngrok http 3000 en una pestaña de terminal y la cerraste sin apretar Ctrl+C, o un script crasheó sin limpiar, el proceso de ngrok sigue corriendo en segundo plano, ocupando tu única sesión permitida, invisible a menos que lo busques activamente.

Encuentra el proceso huérfano

pgrep ngrok

pgrep devuelve el PID de cualquier proceso ngrok en ejecución, si existe. Para más detalle (línea de comando completa, cuánto tiempo lleva corriendo):

ps aux | grep ngrok

Mátalo

Con la confirmación de que está corriendo:

killall ngrok

killall busca por nombre de proceso, así que no importa qué pestaña de terminal o script lo inició, ni si esa pestaña sigue abierta. Si preferís apuntarle por PID (útil si killall responde “No matching processes”):

kill -9 $(pgrep ngrok)

Reintenta ngrok http 3000 después de cualquiera de los dos. Si el error desapareció, ese era todo el problema.

Confirma qué está tuneando ahora mismo

Antes de matar nada, o para confirmar después, ngrok expone una API local que lista cada túnel activo del agente en ejecución:

curl -s http://127.0.0.1:4040/api/tunnels

Esto pega contra la interfaz web local de ngrok, no contra internet, así que funciona aunque no recuerdes qué puerto tuneaste. Si curl no logra conectar, no hay ningún agente ngrok corriendo localmente, y el conflicto viene de otro lado por completo (otra máquina con la misma cuenta, o la sesión de un compañero).

Cuando el problema es el propio puerto 4040

La interfaz web local y la API de ngrok corren en el puerto 4040 por defecto. Si algo más ya está usando ese puerto, el dashboard de ngrok no arranca, aunque el túnel en sí podría estar funcionando bien. Revisa qué lo está ocupando igual que cualquier otro conflicto de puerto:

lsof -i :4040

Si necesitás el 4040 libre para otra cosa, apunta el dashboard de ngrok a otro puerto con la opción web_addr en ngrok.yml, o pasa --web-addr por línea de comando.

Cómo evitar que vuelva a pasar

La solución es casi siempre disciplina de limpieza: cierra túneles con Ctrl+C, no simplemente cerrando la ventana o pestaña de terminal. Si iniciás ngrok desde un script (común con pyngrok o wrappers similares), asegúrate de que el script llame al equivalente de ngrok.kill() en un bloque finally o al salir, no solo en el camino feliz. Un script que crashea es exactamente cómo un túnel queda huérfano sin que nadie cierre nada a propósito.

Vale la pena recordar: un túnel huérfano sigue exponiendo tu máquina

Esto no es solo una molestia que te impide abrir un túnel nuevo. Hasta que lo mates, ese túnel de ngrok olvidado sigue reenviando una URL pública directo a lo que sea que esté corriendo en tu puerto local, abierto a internet, sin que nadie lo esté vigilando. Un túnel que olvidaste es un túnel que nadie está revisando por tráfico inesperado.

Preguntas rápidas

¿Cómo reviso si ngrok ya está corriendo antes de abrir un túnel nuevo? curl -s http://127.0.0.1:4040/api/tunnels. Si devuelve datos de túnel, ya hay uno activo; si la conexión es rechazada, no hay nada corriendo localmente.

killall ngrok dice que no hay procesos coincidentes, pero el error persiste. La sesión podría estar en otra máquina asociada a la misma cuenta de ngrok (un compañero, un runner de CI, otra Mac), algo que killall en tu máquina obviamente no puede tocar. Revisa la sección “Sessions” o “Endpoints” de tu dashboard de ngrok online para encontrarla y detenerla remotamente.

¿Esto aplica también a Cloudflare Tunnel? Los códigos de error específicos son de ngrok, pero el patrón de fondo, un proceso de agente huérfano que quedó corriendo de una sesión olvidada, aplica igual a cloudflared. Búscalo con pgrep cloudflared en vez de ngrok.

El conflicto de puerto no es ngrok en absoluto, es mi servidor de desarrollo. Ese es un problema distinto y más común, explicado paso a paso en ¿Puerto 3000 ocupado en tu Mac?.