ClientHost receives
the request, runs the diagnostics locally (probing UDP connectivity, NAT
behavior, relay latency, and port mapping), and returns the report to iroh services for
display.
To wire net diagnostics into your own application, follow Diagnose a connectivity issue. This page is the reference for reading the report it produces and fixing common setup problems.
Understanding Reports
NAT Types
| NAT Type | What it means | Connection quality |
|---|---|---|
| No NAT | Local address matches public address | Direct connections work with correct firewall config |
| Endpoint-Independent | One outbound UDP packet opens a port for any sender | NAT traversal works reliably |
| Endpoint-Dependent | Only the specific destination can reply (symmetric NAT) | Connections will primarily use relays |
| Unknown | NAT behavior could not be determined | Check UDP connectivity |
Connectivity Summary
The report includes a color-coded connectivity summary:- Green: UDP works and NAT is favorable. Direct connections should work.
- Orange: Endpoint-Dependent NAT. Direct connections may be difficult; traffic will often be relayed.
- Red: No UDP connectivity. Traffic will be relayed.
Troubleshooting
The capability grant (NetDiagnosticsCap::GetAny) authorizes the platform to
request diagnostics from your endpoint. Without this grant, the Run
Diagnostics button will be disabled in the dashboard even if the endpoint is
online.
If the button is enabled but the report never arrives, your endpoint is not
accepting CLIENT_HOST_ALPN. The grant only tells the platform that it may dial
back; the endpoint still has to answer that dial with a ClientHost. Confirm
that you call .accept(CLIENT_HOST_ALPN, ClientHost::new(&endpoint)) on the
router you spawn for this endpoint, that the call happens before .spawn(), and
that the router stays alive for as long as the endpoint does.