Troubleshooting

Work down the list. Each step rules out one layer.

Two things fix a surprising share of problems: Health under Environment, which re-runs every environment check, and Repair on the Virtual Hosts panel, which puts /etc/hosts back in agreement with your site list.

The domain does not resolve

The browser cannot find the server at all, before any request is made.

  • Check the site is enabled. A disabled site has no hosts entry.
  • Check the entry: grep myapp.test /etc/hosts. It should appear on both the 127.0.0.1 and the ::1 line. If it is missing, press Repair.
  • Flush the DNS cache: sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder
  • If the domain ends in .local, use .test instead — multicast DNS answers first.

It resolves, but the connection is refused

The name is right and nothing is listening.

  • Is Apache running? Check the sidebar indicator, or the Apache panel.
  • If it will not start, its configuration does not parse. Health shows the error, which names the file and line.
  • Is something else holding 80 or 443? See ports.

Every page is 503

For a proxy site this means Apache is fine and your dev server is not answering.

  • Start the dev server.
  • Confirm it is on the port the site forwards to, and that it is bound to localhost — a server listening only on a container-internal interface will not answer.
  • Check the port in the Ports panel to see what, if anything, holds it.

A proxy site returns 500

Usually a missing module. Proxying needs mod_proxy, mod_proxy_http, mod_proxy_wstunnel and mod_rewrite; open the Apache panel and enable the ones that are off. The site's error log will name the directive Apache did not recognise.

WebSockets or hot reload will not connect

mod_proxy_wstunnel is off. Same panel. Everything else about the site will look fine, because only the upgrade request fails.

Apache serves the PHP file instead of running it

The PHP module is not loaded. Open the PHP panel and press Switch and restart on the version you want — that rewrites the LoadModule php_module line and uncomments it if it was commented out.

The browser warns about the certificate

  • "Not private" on a site that used to work — the certificate follows the hostname. If you renamed the site, re-issue from the SSL panel.
  • Every HTTPS site warns — the local authority is not trusted. Press Trust local CA on the SSL panel.
  • The certificate is self-signed — Homebrew could not install mkcert when HTTPS was enabled. Install it from Health, then re-issue from the SSL panel.
  • Trusting fails with "no user interaction was possible" — run the system-wide command the app shows you, in Terminal. See HTTPS and certificates.
  • Firefox still warns — it has its own trust store. Set security.enterprise_roots.enabled in about:config.

HTTPS shows the wrong site, or a certificate for another name

Apache serves the first :443 block that matches when it cannot tell hosts apart. Check that the site has its own block under Preview config, and that no two sites share a ServerName.

Changes to a vhost block keep disappearing

The vhost files are generated. Editing a site in the app rewrites its whole block, so hand edits inside it are lost. Put extra directives in an .htaccess file in the document root, or in your own config file included from httpd.conf.

It worked yesterday, and now it asks for a password

A macOS update or a Homebrew upgrade can reset file ownership or remove the sudoers rule. Open Health — it will report which file is no longer writable — and relaunch the app to be offered the one-time setup again.

500 on a static site

Read that site's error log under Environment → Logs. A PHP fatal appears there with file and line. If the log is empty, the failure is Apache's rather than PHP's, and error_log in the same directory will have it.

Undoing something

Every change that touches a site takes a backup first. Sites → Backups lets you preview one and restore it, then run Repair to bring /etc/hosts back in line.

Still stuck

Open an issue with the app's version, your macOS version, and the relevant lines from the error log: github.com/vhostly/vhostly/issues.