Troubleshooting
The most common problems (domain not responding, certificate rejected, port in use, Docker missing) and how to fix them.
Always start with the status bar at the bottom of the window (or joppa status): it tells you whether the proxy is running, whether the CA is trusted and how many domains respond.
The domain doesn’t respond
The browser can’t find the site (DNS_PROBE_FINISHED_NXDOMAIN). The .test name doesn’t resolve to your machine. See Installation › Resolving .test domains.
“The dev server is not responding” (502). The proxy works, but nothing is listening on the target port. Start the dev server, check its port in the Domains tab, or let Joppa start it from Processes.
“Domain not configured”. This name isn’t attached to any project, or the domain is disabled. Add it in the Domains tab.
Nothing responds at all. The proxy is stopped (banner at the top of the window): Start the proxy.
“Blocked request. This host is not allowed.”
Vite or Astro reject the domain. The Domains tab offers Fix the file. See Framework settings.
The browser shows “Not secure”
The system doesn’t trust the CA: the status bar shows CA … not trusted. Run the command from Settings › Certificate authority, then restart the browser. On Linux, also import the CA into Firefox. See Certificates.
Generated URLs use http://
Your framework doesn’t know it’s behind an HTTPS proxy. Laravel: see Laravel behind a proxy. Other frameworks read X-Forwarded-Proto.
The proxy won’t start
- Lerd holds the ports: the banner offers Stop Lerd and start. See Running alongside Lerd.
- Another program holds port 443 (Valet, nginx, Caddy, another proxy): stop it.
- Linux, permission denied:
sudo setcap cap_net_bind_service=+ep <path to joppa>. - “HTTP → HTTPS redirect disabled”: only port 80 is taken; HTTPS works.
A service won’t start
- “No container runtime”: install or start OrbStack, Docker Desktop, Colima or Podman. See Container runtimes.
- “Port 5432 is used by …”: another PostgreSQL is running (Homebrew, Postgres.app, Docker). Free the port or Change port. See Port in use.
- The first time with extensions: building the PostgreSQL image takes a few minutes.
A process keeps crashing
Open the terminal (⌘ J) and the process’s tab: the last error is there. After the chosen number of relaunches, Joppa gives up and says so. See Relaunch after a crash.
The project doesn’t see its new variables
Dev servers only read .env at startup: restart them (from the Processes tab if Joppa runs them).
The joppa command says Joppa isn’t running
Exit code 3. Launch the app, or add --launch. If the app is running, reinstall the command from Settings › Command line.
Still stuck?
Write to us from the app: Support, at the bottom of the sidebar (or “Write to support” in the ⌘ K palette). Joppa’s version and your system are attached to the message. Without an activated licence, the app sends you to getjoppa.com: you get a sign-in link by email, licence or not, and the form opens right after. The same form is also in the website’s footer.
You can also write to [email protected], with the output of joppa status. Just a question: [email protected].