Troubleshooting

Every failure attaches to the thing that failed and shows the underlying message plus one fix action. A failure in one project or server never affects another. nearhost doctor checks most of the causes below at once.

Port 443 or 80 already in use

The proxy refuses to start. Home names the port and, where available, the owning process.

Stop whatever holds the port. Another local proxy is the usual cause: nginx, Caddy, Herd or Valet. On Linux, also check that the binary may bind low ports. See Install.

A loopback port is already bound

The project enters error and shows the port and process. Its other routes still start.

Stop the process, or move the project’s dev server to a different port and edit the route. For Vite that is server.port in the Vite config, or VITE_PORT under Laravel Sail.

Sudo declined

The project stays stopped with “alias not resolvable, press enter to retry”. Press enter on the project and approve the sudo prompt. See The hosts file.

Keychain trust declined

The proxy still runs. Home shows the CA as untrusted with the nearhost trust hint. Run:

nearhost trust

SSH keeps reconnecting

The server shows reconnecting with backoff and its projects show degraded. Caddy returns 502 meanwhile.

Read the last error on the server view, then run ssh <host> in a terminal. When it connects, press r to reconnect.

Authentication failed three times

Nearhost stops retrying after three consecutive authentication failures. The server shows the fix command. Run ssh <host> in a terminal and handle the host key, passphrase or ssh-add prompt. Then press r.

Discovery found nothing

The wizard allows manual port entry. Add the ports and their roles yourself. See Discovery.

Config file invalid

Nearhost exits with the YAML error and line. Fix that line in ~/.config/nearhost/config.yaml. See config.yaml.