ingressd
Sign inGet started
Docspreview · subject to change
Docs / Reference / Troubleshooting

Troubleshooting

The usual reasons a node does not connect, a tunnel has no handshake or an app's deployment check fails, and what to do about each.

Start with the panel: a failed deployment step or an offline node shows what happened and a hint. The sections below cover the same cases in more detail.

A node does not connect#

shellon the vps
$ ingressd node status
$ journalctl -u ingressd -f
  • Not enrolled: the install did not finish enrolling. Create a new token in the panel and run the installer again; enrolment tokens expire after 24 hours and work once.
  • Can't reach the panel: the node connects out to app.ingressd.com on TCP 443. Check outbound HTTPS from the VPS with curl -I https://app.ingressd.com.
  • Firewall dead-man switch still armed: until the node connects, a timer removes the ingressd firewall table after 5 minutes. That is expected; it is cancelled once the node connects.

A node that loses the panel keeps serving its last config. It shows as offline in the panel after 90 seconds without a heartbeat.

A tunnel has no handshake#

Connector homes

  • Check the connector is running: ingressd-connector status, and on Linux systemctl status ingressd-connector.
  • If UDP is blocked on your network, the connector falls back to WebSocket on port 443 by itself. Run it with --debug to see which transport it uses.
  • Check your provider's firewall allows UDP 51820–59999 to the node.

WireGuard routers

  • The tunnel must be enabled on the router and use the config downloaded for that node; each node has its own config.
  • The router must reach the node's endpoint over UDP. Check your provider's firewall for UDP 51820–59999.
  • UniFi refuses an import without a DNS = line. The downloaded file has one; keep it.

App deployment checks#

Step and code What happened What to do
Origin tunnel_down The node has no recent handshake from the home. See a tunnel has no handshake.
Origin no_reply The tunnel is up but the origin never answered: a firewall dropped the connection. Allow the home's site block from the WireGuard interfaces to the origin's IP and port, and check the origin host's own firewall. On UniFi the policy goes from the External zone to Internal.
Origin refused Nothing listens on that port. Check the port and that the service is running.
Origin timeout The origin accepted the connection but sent no HTTP answer. Check it speaks HTTP, or set the origin to https:// if it only serves TLS.
Origin http_error The origin answered with a 5xx error. Check the service's own logs.
DNS dns_missing The hostname doesn't resolve. Create the CNAME to the app's DNS target. New records can take a few minutes to appear.
DNS dns_wrong The hostname points somewhere else. Change it to a CNAME to the DNS target.
DNS dns_proxied The record is proxied by Cloudflare. Set it to DNS only (grey cloud).
Certificate cert_pending The node is obtaining the certificate. Wait; it normally takes under a minute once DNS points at your nodes.
Certificate cert_failed Let's Encrypt refused or could not reach the node. Check DNS, that TCP 80 and 443 are open at your provider, and that no CAA record blocks Let's Encrypt.
Live tls_error The public HTTPS check failed. Usually the certificate is not issued yet; check the certificate step first.

Checks re-run automatically every 30 seconds while a step is failing, and whenever the config, DNS or certificates change.

A game server is unreachable#

  • Check the ports are open in your provider's firewall, for both TCP and UDP if the game uses both.
  • With allowlist or login_to_play access, check the player's IP with ingressd l4 list on a node.
  • In transparent mode, replies must return through the tunnel; switch to proxy mode to rule this out.

Collect diagnostics#

shellon a node
$ ingressd doctor
$ ingressd tunnel status
$ ingressd logs --host media.example.net --status 5xx --since 1h