Troubleshooting

Common issues and how to fix them.

Domain doesn't resolve

  • •Run `hatch status` to check if the daemon is running. Start it with `hatch start`.
  • •Verify the DNS resolver is configured: `scutil --dns | grep test` (macOS) or check `/etc/resolver/test`.
  • •Try `dig myapp.test @127.0.0.1` — if it resolves, the DNS server is working but your OS isn't using it.
  • •Re-run `hatch setup` to reconfigure the DNS resolver.

Browser shows connection refused

  • •Make sure your dev server is actually running on the mapped port.
  • •Check that your dev server binds to `0.0.0.0`, not `127.0.0.1` or `localhost`.
  • •Run `hatch ls` to verify the domain mapping exists and shows the correct port.

HTTPS certificate warning

  • •Run `hatch setup` to install the CA in your system trust store.
  • •If you recently reinstalled your OS or reset keychains, the CA needs to be re-trusted.
  • •In Firefox: go to Settings > Privacy & Security > Certificates > View Certificates > Import the CA from `~/.hatch/ca/`.

HMR / hot reload not working

  • •Your framework's dev server needs to know about the proxy hostname. See the framework-specific guide for the exact config.
  • •Check that WebSocket connections are proxied correctly — Hatch handles this, but some frameworks need `hmr.host` set explicitly.
  • •If using Vite: set `server.hmr.host` and `server.hmr.protocol` in your Vite config.
  • •If using Next.js: add your domain to `allowedDevOrigins` in `next.config.ts`.

Port 80 or 443 already in use

  • •Another server (nginx, Apache, or another proxy) is bound to these ports.
  • •On macOS: `sudo lsof -i :80` to find the process, then stop it.
  • •On Linux: `sudo ss -tlnp | grep :80` to identify the process.
  • •You can change Hatch's ports with `hatch config set http_port 8080` and `hatch config set https_port 8443`, but you'll need to include the port in URLs.

Permission denied during setup

  • •`hatch setup` requires sudo to configure the DNS resolver and bind to privileged ports (80, 443, 53).
  • •On macOS, you may need to allow Hatch in System Settings > Privacy & Security if it's blocked.

Domain works but shows 'waiting' page

  • •The domain is mapped but your dev server isn't running on that port yet. Start your dev server.
  • •The waiting page auto-refreshes when the server comes up.
  • •If the server IS running, check that it's on the correct port with `lsof -i :<port>`.

OAuth callback fails

  • •Update your OAuth provider's redirect URL to use the Hatch domain (e.g. `https://myapp.test/auth/callback`).
  • •Set the appropriate environment variable for your auth library (e.g. `NEXTAUTH_URL`, `NUXT_PUBLIC_APP_URL`).
  • •Make sure HTTPS is enabled — most OAuth providers require it.

Still stuck?

Check the daemon logs with hatch logs -f for real-time debugging, or open an issue on GitHub.