Solución de problemas

Empieza siempre por la barra de estado de la parte inferior de la ventana (o joppa status): indica si el proxy está en marcha, si la CA está aprobada y cuántos dominios responden.

El dominio no responde

joppa diagnose <dominio> (o la herramienta MCP diagnose) comprueba de una vez todo lo que sigue y dice qué corregir: proxy, resolución del nombre, certificado, puerto del servidor de desarrollo y estado del proceso que debe ocuparlo.

El navegador no encuentra el sitio (DNS_PROBE_FINISHED_NXDOMAIN). El nombre .test no se resuelve a tu equipo: la barra de estado muestra .test no resuelve. Haz clic en ella, o en Configurar / Reparar en el aviso: Joppa coloca su archivo de resolución (tu contraseña) y vacía la caché DNS. Ajustes › Resolución de .test › Probar un dominio te dice exactamente qué falla:

Mensaje	Qué hacer
«Ningún archivo del sistema envía todavía .test a Joppa»	Configurar
«El sistema todavía no resuelve …»	Reparar: reescribe el archivo y vacía la caché
«… resuelve a 10.…, no a este equipo»	Una VPN o el DNS de la red responde para .test: Reparar reescribe el archivo de Joppa y vacía la caché; si la VPN impone su DNS, añade el dominio a /etc/hosts
«El servidor DNS de Joppa no está en marcha»	Otro programa ocupa el puerto 15353: libéralo y vuelve a abrir Joppa
«… llega a Joppa, pero ningún proyecto lo enruta»	Añade el dominio a un proyecto

Consulta Instalación › La resolución de los dominios .test.

«El servidor de desarrollo no responde» (502). El proxy funciona, pero nada escucha en el puerto de destino. Inicia el servidor de desarrollo, comprueba su puerto en la pestaña Dominios o deja que Joppa lo inicie desde Procesos.

«Dominio no configurado». Este nombre no está asociado a ningún proyecto, o el dominio está desactivado. Añádelo en la pestaña Dominios.

No responde nada. El proxy está detenido (aviso en la parte superior de la ventana): Iniciar el proxy.

«Blocked request. This host is not allowed.»

Vite o Astro rechazan el dominio. La pestaña Dominios propone Corregir el archivo. Consulta Ajustes del framework.

El navegador muestra «No seguro»

El sistema no ha aprobado la CA: la barra de estado muestra CA … no aprobada. Haz clic en Aprobar en el aviso de la parte superior de la ventana (o en Aprobar la autoridad en Ajustes › Autoridad de certificación) y reinicia el navegador. En Linux, importa también la CA en Firefox. Consulta Certificados.

Las URL generadas están en http://

Tu framework no sabe que está detrás de un proxy HTTPS. Laravel: consulta Laravel detrás de un proxy. Los demás frameworks leen X-Forwarded-Proto.

El proxy no se inicia

• Otro servidor ocupa el puerto 443 (Lerd, Laravel Herd, Valet, Apache, Caddy, MAMP, DDEV, un contenedor…): el aviso lo nombra («El puerto 443 lo ocupa …») y propone detenerlo, y luego inicia el proxy. Consulta Puertos 80 y 443 ocupados.
• El aviso no sabe quién es («un proceso de otro usuario»): ejecuta el comando que se muestra (sudo lsof -nP -iTCP:443 -sTCP:LISTEN), detén ese programa y luego Iniciar el proxy.
• Linux, permiso denegado: sudo setcap cap_net_bind_service=+ep <ruta de joppa>.
• «Redirección HTTP → HTTPS desactivada»: solo el puerto 80 está ocupado; HTTPS funciona.

Un servicio no se inicia

• «Ningún runtime de contenedores»: instala o inicia OrbStack, Docker Desktop, Colima o Podman. Consulta Runtimes de contenedores.
• «El puerto 5432 está ocupado por …»: hay otro PostgreSQL en marcha (Homebrew, Postgres.app, Docker). Liberar el puerto o Cambiar de puerto. Consulta Puerto ocupado.
• La primera vez con extensiones: la construcción de la imagen de PostgreSQL tarda unos minutos.

Un proceso falla una y otra vez

Abre la terminal (⌘ J) y la pestaña del proceso: ahí está el último error. Tras el número de reinicios elegido, Joppa se rinde y lo indica. Consulta Reiniciar tras un fallo.

El proyecto no ve sus nuevas variables

Los servidores de desarrollo solo leen el .env al arrancar: reinícialos (desde la pestaña Procesos si los inicia Joppa).

Vite+ no se instala

Joppa instala Vite+ en el primer arranque; sin conexión, la instalación falla y las plantillas de JavaScript siguen en gris. Cuando tengas conexión, pulsa Reintentar en la ventana Nuevo proyecto o en Ajustes › Node. La instalación descarga el script oficial de https://vite.plus y luego Node LTS y bun desde sus sitios. Consulta Versiones de Node, bun y PHP.

El móvil no abre el sitio compartido

Para compartir en la red local:

• Misma red. El móvil debe estar en la misma Wi-Fi que el Mac, no en 4G/5G. Una Wi-Fi de «invitados» o pública suele aislar los dispositivos entre sí: prueba otra red, o un enlace público.
• Firewall de macOS. Si rechazaste la solicitud de conexiones entrantes: Ajustes del Sistema › Red › Firewall › Opciones, y permite Joppa. Con «Bloquear todas las conexiones entrantes» marcado, no pasa nada.
• VPN. Una VPN activa en el Mac puede hacer que se muestre su dirección en lugar de la de la Wi-Fi. Desactívala y luego desactiva y vuelve a activar el uso compartido.
• La página se muestra pero no sus scripts o su API: vienen de otro dominio .test, que el móvil no conoce. Comparte también ese dominio, o consulta Lo que ve la aplicación.
• La sesión no se mantiene (vuelves a la página de inicio de sesión): una cookie __Secure- o __Host- exige HTTPS; usa un enlace público.

El enlace público no se abre

• «El túnel se cerró»: la ventana muestra los últimos mensajes del cliente. Lo más habitual es que la red bloquee la salida (proxy de empresa, firewall) o que el servicio no esté disponible en ese momento; pulsa Reintentar, o elige otro túnel.
• cloudflared se niega a crear un túnel rápido cuando existe un archivo ~/.cloudflared/config.yml (o config.yaml) (el de un túnel con nombre): renómbralo mientras compartes.
• ngrok: sin token (en Joppa o con ngrok config add-authtoken), ngrok no arranca.
• Pinggy cierra un túnel gratuito a los 60 minutos: vuelve a abrirlo (la dirección cambia).
• La descarga de cloudflared falla con «suma de comprobación no válida»: el archivo recibido no es el publicado por Cloudflare (un proxy que modifica las descargas, un archivo dañado). Joppa lo ha eliminado; vuelve a intentarlo en otra red, o instala cloudflared tú mismo (brew install cloudflared).

El comando joppa dice que Joppa no está en marcha

Código de salida 3. Inicia la app o añade --launch. Si la app está en marcha, reinstala el comando desde Ajustes › Línea de comandos.

Informar de un error

Informar de un error, en la parte inferior de la barra lateral (o en la paleta ⌘ K), envía un informe al equipo, sin cuenta:

1. Con una licencia activada en este Mac, el formulario se abre directamente: respondemos a la dirección de la licencia.
2. Si no, escribe tu dirección de correo y haz clic en Recibir un código: llega un código de 6 cifras por correo. Escríbelo y luego Verificar. La dirección se recuerda 30 días en este Mac; Cambiar de dirección la olvida.
3. Describe Qué falla, luego los Detalles (qué estabas haciendo, qué pasó, qué esperabas) y Enviar el informe (⌘ ↵).

Se adjuntan la versión de Joppa y tu sistema. Recibes una copia con una referencia (JP-…); respondemos a tu dirección.

Adjuntar los registros recientes, activado por defecto, añade las últimas líneas del registro de Joppa (150 KB como máximo), con tu carpeta personal escrita ~. Ver lo que se envía las muestra antes del envío. Llegan al equipo como archivo adjunto del informe y no se guardan en el sitio web.

Documentación, justo encima, abre esta documentación en el idioma de la app.

¿Sigues atascado?

Escríbenos desde la app: Soporte, abajo en la barra lateral (o «Escribir al soporte» en la paleta ⌘ K). Se adjuntan la versión de Joppa y tu sistema. Sin una licencia activada, la app te lleva a getjoppa.com: recibes un enlace de inicio de sesión por correo, con o sin licencia, y el formulario se abre justo después. El mismo formulario está en el pie de página de la web.

También puedes escribir a [email protected], con la salida de joppa status. Para una simple pregunta: [email protected].