Troubleshooting

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

joppa diagnose <domain> (or the diagnose MCP tool) checks everything below in one go and tells you what to fix: proxy, name resolution, certificate, the dev server’s port and the state of the process that should be using it.

The browser can’t find the site (DNS_PROBE_FINISHED_NXDOMAIN). The .test name doesn’t resolve to your machine: the status bar shows .test not resolving. Click it, or Set up / Repair in the banner: Joppa writes its resolver file (your password) and flushes the DNS cache. Settings › .test resolution › Test a domain tells you exactly what’s wrong:

Message	What to do
“No system file sends .test to Joppa yet”	Set up
“The system doesn’t resolve … yet”	Repair: rewrites the file and flushes the cache
“… resolves to 10.…, not to this computer”	A VPN or your network’s DNS answers for .test: Repair rewrites Joppa’s file and flushes the cache; if the VPN forces its DNS, add the domain to /etc/hosts
“Joppa’s DNS server isn’t running”	Port 15353 is taken by another program: free it, then restart Joppa
“… reaches Joppa, but no project routes it”	Add the domain to a project

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. Click Approve in the banner at the top of the window (or Approve the authority in 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

• Another server holds port 443 (Lerd, Laravel Herd, Valet, Apache, Caddy, MAMP, DDEV, a container…): the banner names it (“Port 443 is held by …”) and offers to stop it, then starts the proxy. See Ports 80 and 443 in use.
• The banner can’t tell who it is (“a process of another user”): run the command it shows (sudo lsof -nP -iTCP:443 -sTCP:LISTEN), stop that program, then Start the proxy.
• 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).

Vite+ doesn’t install

Joppa installs Vite+ at first launch; offline, the install fails and the JavaScript templates stay greyed out. Once online, click Retry in the New project window or in Settings › Node. The install downloads the official script from https://vite.plus, then Node LTS and bun from their sites. See Node, bun and PHP versions.

The phone doesn’t open the shared site

For sharing on the local network:

• Same network. The phone must be on the same Wi-Fi as the Mac, not on 4G/5G. A “guest” or public Wi-Fi often isolates devices from each other: try another network, or a public link.
• macOS firewall. If you denied the incoming connections prompt: System Settings › Network › Firewall › Options, and allow Joppa. With “Block all incoming connections” checked, nothing gets through.
• VPN. A VPN running on the Mac can make Joppa show its address instead of the Wi-Fi one. Turn it off, then turn sharing off and on again.
• The page shows but not its scripts or its API: they come from another .test domain, which the phone doesn’t know. Share that domain too, or see What the app sees.
• The login doesn’t hold (you’re sent back to the login page): a __Secure- or __Host- cookie requires HTTPS; use a public link.

The public link doesn’t open

• “The tunnel closed”: the window shows the client’s last messages. Most often, the network blocks outgoing traffic (corporate proxy, firewall) or the service is briefly unavailable; click Retry, or pick another tunnel.
• cloudflared refuses to create a quick tunnel when a ~/.cloudflared/config.yml (or config.yaml) file exists (one for a named tunnel): rename it while you share.
• ngrok: without an authtoken (in Joppa or through ngrok config add-authtoken), ngrok refuses to start.
• Pinggy closes a free tunnel after 60 minutes: open it again (the address changes).
• The cloudflared download fails with “invalid checksum”: the archive received isn’t the one Cloudflare published (a proxy that alters downloads, a corrupted file). Joppa deleted it; try again on another network, or install cloudflared yourself (brew install cloudflared).

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.

Report a bug

Report a bug, at the bottom of the sidebar (or in the ⌘ K palette), sends a report to the team, no account needed:

1. With a license activated on this Mac, the form opens right away: we reply to the license’s address.
2. Otherwise, enter your e-mail address and click Get a code: a 6-digit code arrives by e-mail. Type it, then Verify. The address is remembered for 30 days on this Mac; Change address forgets it.
3. Describe What’s wrong, then the Details (what you were doing, what happened, what you expected), and Send the report (⌘ ↵).

Joppa’s version and your system are attached. You get a copy with a reference (JP-…); we reply to your address.

Attach the recent logs, on by default, adds the latest lines of Joppa’s log (150 KB at most), your home folder written ~. See what is sent shows them before sending. They reach the team as an attachment to the report and are not kept on the website.

Documentation, just above, opens these docs in the app’s language.

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].