Troubleshooting
Trace a failed connection from endpoint to application.
Work through the symptom that matches what you see. Each list runs from the most common cause to the least. Console pages are named as they appear in the side menu. Host commands are the ones the agent and gateway actually ship: pulsectl on Linux endpoints, pulseha-gateway on gateways, and journalctl for both.
Where to find agent logs:
| Platform | Service | Logs |
|---|---|---|
| Linux | pulseha-agent (systemd) | journalctl -u pulseha-agent -f |
| macOS | com.pulseha.agentd (launchd) | /var/log/pulseha/agentd.log and agentd.err.log |
| Windows | PulseHAAgent | %PROGRAMDATA%\PulseHA\logs\agent.log and the Windows Event Log |
pulsectl diagnostics writes a support bundle (logs, status, network snapshot) you can attach to a ticket.
Device will not connect#
- Check lifecycle state. Open Network → Devices. A device shown as Pending has not finished browser authorization; restart
pulsectl loginor the app sign-in. Blocked, Archived and Revoked devices do not connect. Blocked and archived can be restored from the device drawer (Restore Device). Revoked cannot; enroll again. - Check the account. On the host, run
pulsectl status. If it shows “not logged in”, runpulsectl login. Each user may hold at most 5 devices; a sixth authorization is refused. - Check control reachability. The agent talks to
https://api.pulseha.comover HTTPS. A corporate proxy or firewall that blocks it stops registration and heartbeats. Look for register or heartbeat errors in the agent log. - Check the tunnel interface.
pulsectl statusshould show a tunnel IP. On Linux,ip link show pha0should exist. If NetworkManager keeps resetting it, confirm/etc/NetworkManager/conf.d/pulseha-unmanaged.confis present; the agent writes it on first start. - Check for a posture block. If the device shows Non-compliant and a Device Posture policy is in Enforce mode with a blocking action, the agent disconnects on purpose.
pulsectl statusshows a warning beneath the connection state. See Security → Device Posture. - Check the gateway handshake.
pulsectl gatewayslists each gateway peer with its last handshake. No handshake with every gateway usually means UDP cannot leave the network or reach the gateway. See “Gateway offline” below for the gateway side. - Check the device policy. A Device Policy with Kill Switch or Disable Disconnect set to Enforce On changes what the user can do locally. Network → Devices → Device Policies shows which policy applies.

The device drawer on its Posture tab. The device is Online but Non-compliant; the effective policy is in monitor mode, so this alone does not block access.
Device connected but no access#
The device is Online and has a tunnel IP, but an application does not load.
- Confirm the service exists and is reachable from a gateway. Open Network → Services. Check the Target (address, protocol, port) and the Gateways column. The Health chip must not be DOWN. NOT MONITORED only means no probe is configured.
- Confirm a policy grants it. Open Network → Access → Access Policies. A matching Allow policy must be Enabled, include the service, and include the device (directly, through its user, or through a group). A policy with Selected subjects and nobody selected matches nobody. Traffic matching no policy is denied.
- Check for a higher-priority Deny. Lower priority numbers evaluate first. On equal priority, Deny wins. Use Simulate on the Access page to see the chain and the deciding policy.
- Confirm the route reached the device.
pulsectl gatewaysprints each peer’s allowed IPs. The service CIDR should appear under exactly one gateway. If it is missing, runpulsectl refreshand check again. A Hostname service only produces a route when its address is an IP literal. - Confirm the gateway can reach the application. On the gateway host, test the target from the LAN side with
curlornc. The gateway forwards with source NAT fromwg0out of its LAN interface, so the application sees the gateway’s LAN address. - Check firewall rules. Security → Firewall rules run ahead of access rules on the gateway. A Deny or Reject rule that matches the flow is final. Check the rule’s application status; Applied requires the gateway to have reported it.
- Check the audit trail. Security → Audit records access decisions and posture events around the failure time.

Audit filtered to Access. Each Denied row names the device, the gateway and the destination, so you can match it to the policy that refused the flow.
Gateway offline#
- Check the service on the host.
sudo systemctl status pulseha-gatewayandsudo journalctl -u pulseha-gateway -fwork on every host. The unit restarts on failure, so a crash loop shows as repeated starts. With version 2.20.0 or later (pulseha-gateway version --short),sudo pulseha-gateway statusalso shows whether the service is healthy, when it last reached PulseHA, its last configuration sync and policy, and how old each of those facts is, andsudo pulseha-gateway logs -ffollows the log. - Run the built-in check.
sudo pulseha-gateway doctorverifies host prerequisites on every gateway. From 2.20.0 it groups its checks by area (system, dependencies, WireGuard, enrollment, control connection, service, scanner, access records, updates, proxy and inspection) and prints afix:line under every warning and failure, and neither it norstatuschanges anything; add--jsonfor scripts. The health endpointcurl http://127.0.0.1:8080/healthzanswers locally. See Gateway command line for every command, its exit codes, and what to use on an older gateway. - Check control reachability. The gateway polls
https://gw-api.pulseha.comwith mutual TLS every 60 seconds and heartbeats every 10 seconds. Control marks a gateway Offline when its last heartbeat is older than 90 seconds. An expired or missing certificate in/var/lib/pulseha/gatewayshows as TLS errors in the journal. On gateway 2.20.0 or later,doctoralso tests the connection with full certificate checks and says when a proxy or firewall that inspects TLS is replacing PulseHA’s certificate. - Check for revocation. A removed gateway receives a revoked response, clears its policy and exits. Network → Gateways shows Revoked in the detail drawer. Re-enroll with a fresh code from Add Gateway; codes are single use and expire after 24 hours. On gateway 2.20.0 or later run
sudo pulseha-gateway login --force --code phgw_..., which keeps the old enrollment if the new code is refused. On an older gateway runsudo pulseha-gateway logout --force, thensudo pulseha-gateway login --code phgw_.... - Check the version. An Upgrade required chip means control returned 426 and will not serve config until the package is updated. On gateway 2.20.0 or later,
sudo pulseha-gateway update checkshows whether a remote update is on offer for the gateway. - Check inbound UDP. Devices reach the gateway on UDP 51820 by default. The package postinstall does not open this port in ufw or firewalld; open it yourself.
- Check IP forwarding. Startup fails if
sysctl net.ipv4.ip_forwardis not 1. The package installs a sysctl drop-in; a host image that overrides it breaks forwarding.

The Gateways list with one Degraded and one Offline gateway. The offline gateway also carries an Upgrade required chip, which by itself stops control serving it configuration.
DNS not resolving#
- Understand the path. The agent points the OS at a loopback forwarder on
127.0.0.1:53, which forwards to the gateway’s resolver on the gateway tunnel IP. The gateway answers private service names itself and forwards everything else upstream (1.1.1.1 and 8.8.8.8 by default). Private names are also written into the hosts file, so they resolve even if the forwarder is down. - Confirm service discovery is on. Settings → DNS must have Enable DNS switched on. Each service needs a DNS Name, either explicit or auto-generated. The Service Records table shows what will be published.
- Confirm the device has the service. Records are built only for services the device is allowed to reach. No policy means no record.
- Check the OS resolver. Linux:
resolvectl status pha0when systemd-resolved is the system resolver; otherwise look at/etc/resolv.conf(the agent keeps a backup at/etc/resolv.conf.pulseha.bak). Windows: the agent installs a catch-all NRPT rule; another product’s catch-all rule can hijack it, and the agent logs a warning when it detects one. macOS:scutil --dnsshows thepha0resolver entry. - Check the gateway resolver. On the gateway,
journalctl -u pulseha-gatewayshows DNS forwarder errors. The resolver rate-limits to 100 queries per second per source. - Check for a Secure Web block. A filtered domain returns NXDOMAIN with a TXT record beginning
blocked:. Security → Audit under Content Filter lists these decisions. - Check for a device policy override. A Device Policy with DNS Servers set replaces the gateway resolver entirely, and Secure Web filtering no longer applies to that device.
Slow throughput#
- Check which gateway is active.
pulsectl gatewaysshows the current peer per service. On the gateway,sudo pulseha-gateway peers(2.20.0 or later;status --peers-onlybefore that) lists which devices are connected. The agent ranks healthy gateways by admin priority, then load, then latency. A distant or busy gateway can win if the nearer one is unhealthy for that service. - Check the path type. If the agent is using a relay candidate instead of the direct endpoint, traffic transits an Orbit relay. Fix inbound UDP on the gateway or NAT behaviour on the client network so the direct path handshakes.
- Check MTU. The agent sets 1380 on Linux and 1280 on Windows. If a network path still fragments, large transfers stall while small requests work. Compare
ping -M do -s 1300 <tunnel ip>results. - Check gateway load. The gateway detail drawer shows Connected Sessions, Data Received and Data Sent. The Performance tab and the gateway’s Prometheus endpoint (
127.0.0.1:9090/metrics) show CPU and memory. Add a second gateway and assign the service to both. - Check Secure Web inspection. TLS inspection adds latency on exit traffic. Compare a private service (not inspected) with an internet destination.