Troubleshooting
Run diagnostics first
Section titled “Run diagnostics first”nila-tunnel doctorChecks CA presence, trust status, port availability, DNS resolver, and config.
Common issues
Section titled “Common issues””Certificate not trusted” in browser
Section titled “”Certificate not trusted” in browser”Cause: Root CA not in the OS trust store.
nila-tunnel stopnila-tunnel start # re-trusts CA on first runDomain doesn’t resolve
Section titled “Domain doesn’t resolve”Cause: DNS resolver not registered.
# Verify resolver exists (macOS)cat /etc/resolver/test# Should show: nameserver 127.0.0.1 / port 15353
# If missing, restart to re-registernila-tunnel stop && nila-tunnel startPort 8443 busy
Section titled “Port 8443 busy”Cause: Another nila-tunnel instance is running.
nila-tunnel stopnila-tunnel start”Operation not permitted” on stop
Section titled “”Operation not permitted” on stop”Cause: Proxy was started with sudo.
sudo nila-tunnel stopTwo password prompts during install (macOS)
Section titled “Two password prompts during install (macOS)”macOS Big Sur+ triggers a separate authorization UI for certificate trust settings. This is a platform constraint — one-time setup.
# Daemon logstail -f ~/.nila-tunnel/nila-tunnel.log
# Verbose outputRUST_LOG=nila_tunnel_core=debug nila-tunnel start -FClean reinstall
Section titled “Clean reinstall”nila-tunnel uninstallnila-tunnel installnila-tunnel start