Solución de problemas
Los problemas más habituales, dominio que no responde, certificado rechazado, puerto ocupado, Docker ausente, y cómo resolverlos.
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
El navegador no encuentra el sitio (DNS_PROBE_FINISHED_NXDOMAIN). El nombre .test no se resuelve a tu equipo. 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. Ejecuta el comando de 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
- Lerd tiene los puertos: el aviso propone Detener Lerd e iniciar. Consulta Convivir con Lerd.
- Otro programa tiene el puerto 443 (Valet, nginx, Caddy, otro proxy): detenlo.
- 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).
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.
¿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].