Dépannage

Commencez toujours par la barre d’état en bas de la fenêtre (ou joppa status) : elle dit si le proxy tourne, si la CA est approuvée et combien de domaines répondent.

Le domaine ne répond pas

joppa diagnose <domaine> (ou l’outil MCP diagnose) vérifie tout ce qui suit d’un coup et dit quoi corriger : proxy, résolution du nom, certificat, port du serveur de dev et état du processus qui doit l’occuper.

Le navigateur ne trouve pas le site (DNS_PROBE_FINISHED_NXDOMAIN). Le nom .test ne résout pas vers votre machine : la barre d’état affiche .test ne résout pas. Cliquez dessus, ou sur Configurer / Réparer dans le bandeau : Joppa pose son fichier de résolution (votre mot de passe) et vide le cache DNS. Réglages › Résolution .test › Tester un domaine dit précisément ce qui coince :

Message	Ce qu’il faut faire
« Aucun fichier du système n’envoie encore .test à Joppa »	Configurer
« Le système ne résout pas encore … »	Réparer : réécrit le fichier et vide le cache
« … résout vers 10.…, pas vers cet ordinateur »	Un VPN ou le DNS du réseau répond pour .test : Réparer réécrit le fichier de Joppa et vide le cache ; si le VPN impose son DNS, ajoutez le domaine à /etc/hosts
« Le serveur DNS de Joppa ne tourne pas »	Le port 15353 est pris par un autre programme : libérez-le, puis relancez Joppa
« … arrive bien à Joppa, mais aucun projet ne le route »	Ajoutez le domaine à un projet

Voir Installation › La résolution des domaines .test.

« Le serveur de dev ne répond pas » (502). Le proxy fonctionne, mais rien n’écoute sur le port cible. Lancez le serveur de dev, vérifiez son port dans l’onglet Domaines, ou laissez Joppa le lancer depuis Processus.

« Domaine non configuré ». Ce nom n’est attaché à aucun projet, ou le domaine est désactivé. Ajoutez-le dans l’onglet Domaines.

Rien ne répond du tout. Le proxy est arrêté (bandeau en haut de la fenêtre) : Démarrer le proxy.

« Blocked request. This host is not allowed. »

Vite ou Astro refusent le domaine. L’onglet Domaines propose Corriger le fichier. Voir Réglages du framework.

Le navigateur affiche « Non sécurisé »

La CA n’est pas approuvée par le système : la barre d’état affiche CA … non approuvée. Cliquez sur Approuver dans le bandeau en haut de la fenêtre (ou Approuver l’autorité dans Réglages › Autorité de certification), puis redémarrez le navigateur. Sous Linux, importez aussi la CA dans Firefox. Voir Certificats.

Les URL générées sont en http://

Votre framework ne sait pas qu’il est derrière un proxy HTTPS. Laravel : voir Laravel derrière un proxy. Les autres frameworks lisent X-Forwarded-Proto.

Le proxy ne démarre pas

• Un autre serveur tient le port 443 (Lerd, Laravel Herd, Valet, Apache, Caddy, MAMP, DDEV, un conteneur…) : le bandeau le nomme (« Le port 443 est tenu par … ») et propose de l’arrêter, puis démarre le proxy. Voir Ports 80 et 443 occupés.
• Le bandeau ne sait pas qui c’est (« un processus d’un autre utilisateur ») : lancez la commande affichée (sudo lsof -nP -iTCP:443 -sTCP:LISTEN), arrêtez ce programme, puis Démarrer le proxy.
• Linux, permission refusée : sudo setcap cap_net_bind_service=+ep <chemin de joppa>.
• « Redirection HTTP → HTTPS désactivée » : seul le port 80 est pris ; HTTPS fonctionne.

Un service ne démarre pas

• « Aucun runtime de conteneurs » : installez ou lancez OrbStack, Docker Desktop, Colima ou Podman. Voir Runtimes de conteneurs.
• « Le port 5432 est occupé par … » : un autre PostgreSQL tourne (Homebrew, Postgres.app, Docker). Libérer le port ou Changer de port. Voir Port occupé.
• La première fois avec des extensions : la construction de l’image PostgreSQL prend quelques minutes.

Un processus plante en boucle

Ouvrez le terminal (⌘ J) et l’onglet du processus : la dernière erreur y est. Après le nombre de relances choisi, Joppa abandonne et l’indique. Voir Relancer après un plantage.

Le projet ne voit pas ses nouvelles variables

Les serveurs de dev ne relisent le .env qu’au démarrage : redémarrez-les (depuis l’onglet Processus si Joppa les lance).

Vite+ ne s’installe pas

Joppa installe Vite+ au premier lancement ; sans connexion, l’installation échoue et les modèles JavaScript restent grisés. Une fois en ligne, cliquez sur Réessayer dans la fenêtre Nouveau projet ou dans Réglages › Node. L’installation télécharge le script officiel de https://vite.plus, puis Node LTS et bun depuis leurs sites. Voir Versions de Node, bun et PHP.

Le téléphone n’ouvre pas le site partagé

Pour un partage sur le réseau local :

• Même réseau. Le téléphone doit être sur le même Wi-Fi que le Mac, pas en 4G/5G. Un Wi-Fi « invités » ou public isole souvent les appareils les uns des autres : essayez un autre réseau, ou un lien public.
• Pare-feu de macOS. Si vous avez refusé la demande de connexions entrantes : Réglages Système › Réseau › Coupe-feu › Options, et autorisez Joppa. Avec « Bloquer toutes les connexions entrantes » coché, rien ne passe.
• VPN. Un VPN actif sur le Mac peut faire afficher son adresse au lieu de celle du Wi-Fi. Coupez-le, puis désactivez et réactivez le partage.
• La page s’affiche mais pas ses scripts ou son API : ils viennent d’un autre domaine .test, que le téléphone ne connaît pas. Partagez aussi ce domaine, ou voir Ce que voit l’application.
• La connexion ne tient pas (vous êtes renvoyé à la page de connexion) : un cookie __Secure- ou __Host- exige HTTPS ; passez par un lien public.

Le lien public ne s’ouvre pas

• « Le tunnel s’est fermé » : la fenêtre affiche les derniers messages du client. Le plus souvent, le réseau bloque la sortie (proxy d’entreprise, pare-feu) ou le service est momentanément indisponible ; Réessayer, ou choisissez un autre tunnel.
• cloudflared refuse de créer un tunnel rapide quand un fichier ~/.cloudflared/config.yml (ou config.yaml) existe (celui d’un tunnel nommé) : renommez-le le temps du partage.
• ngrok : sans jeton (dans Joppa ou dans ngrok config add-authtoken), ngrok refuse de démarrer.
• Pinggy ferme un tunnel gratuit au bout de 60 minutes : rouvrez-le (l’adresse change).
• Le téléchargement de cloudflared échoue avec « somme de contrôle invalide » : l’archive reçue n’est pas celle publiée par Cloudflare (proxy qui modifie les téléchargements, fichier corrompu). Joppa l’a supprimée ; réessayez sur un autre réseau, ou installez cloudflared vous-même (brew install cloudflared).

La commande joppa dit que Joppa n’est pas lancé

Code de sortie 3. Lancez l’app, ou ajoutez --launch. Si l’app tourne, réinstallez la commande depuis Réglages › Ligne de commande.

Signaler un bug

Signaler un bug, en bas de la barre latérale (ou dans la palette ⌘ K), envoie un signalement à l’équipe, sans compte :

1. Avec une licence activée sur ce Mac, le formulaire s’ouvre directement : nous répondons à l’adresse de la licence.
2. Sinon, saisissez votre adresse e-mail et cliquez sur Recevoir un code : un code à 6 chiffres arrive par e-mail. Saisissez-le, puis Vérifier. L’adresse est retenue 30 jours sur ce Mac ; Changer d’adresse l’oublie.
3. Décrivez Ce qui ne va pas, puis les Détails (ce que vous faisiez, ce qui s’est passé, ce que vous attendiez), et Envoyer le signalement (⌘ ↵).

La version de Joppa et votre système sont joints. Vous recevez une copie avec une référence (JP-…) ; nous répondons à votre adresse.

Joindre les journaux récents, activé par défaut, ajoute les dernières lignes du journal de Joppa (150 Ko au plus), votre dossier personnel écrit ~. Voir ce qui est envoyé les affiche avant l’envoi. Elles arrivent à l’équipe en pièce jointe du signalement et ne sont pas conservées sur le site.

Documentation, juste au-dessus, ouvre cette documentation dans la langue de l’app.

Toujours bloqué ?

Écrivez-nous depuis l’app : Support, en bas de la barre latérale (ou « Écrire au support » dans la palette ⌘ K). La version de Joppa et votre système sont joints au message. Sans licence activée, l’app vous envoie sur getjoppa.com : vous recevez un lien de connexion par e-mail, avec ou sans licence, puis le formulaire s’ouvre. Le même formulaire est accessible depuis le pied de page du site.

Vous pouvez aussi écrire à [email protected], avec la sortie de joppa status. Pour une simple question : [email protected].