--- title: "Troubleshooting application access" slug: "troubleshooting-application-access-v7-0" description: "Troubleshoot DNS issues in AppGate ZTNA to connect to protected hosts. Verify configurations, entitlements, and device settings for seamless access." tags: ["Application Access", "Connectivity", "Troubleshooting", "DNS Configuration", "DNS Resolution", "DNS Forwarding"] updated: 2026-11-20T15:23:52Z published: 2026-11-20T15:23:52Z canonical: "support.appgate.com/troubleshooting-application-access-v7-0" --- > ## Documentation Index > Fetch the complete documentation index at: https://support.appgate.com/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshooting application access If users have difficulty connecting through Gateways to protected hosts, work through the DNS and access checks below. For background on how DNS works in AppGate ZTNA, see [DNS and name resolution](/v1/docs/dns-and-name-resolution-v7-0). --- ## Check DNS configuration ### Site Device DNS relies on the Site configuration.Verify that a [DNS resolver](/v1/docs/configuring-sites-v7-0#dns-resolving), a [DNS forwarder](/v1/docs/configuring-sites-v7-0#dns-forwarding), or both are correctly configured. It is normal to configure one or both on the Site where the DNS servers are located. If a user can access services on one Site but not another, the DNS resolver on the failing Site may be misconfigured. ### DNS policy [Entitlements](/v1/docs/using-entitlements-v7-0) set routes to protected networks and rely on DNS to resolve protected hosts. AppGate ZTNA routes only DNS requests that match a specified domain through the tunnel to the specified DNS servers. Verify that the hostnames used in entitlements have a matching [domain specified in the DNS policy.](/v1/docs/configuring-policies-v7-0#dns-policy) For mobile devices, you must configure a [default DNS server](/v1/docs/device-dns-configuration-v7-0). ### DNS entitlement The DNS servers specified in the DNS policy require an entitlement that routes DNS requests through the appropriate tunnel toward the Gateway or Site hosting those servers. Verify that an entitlement provides access to the DNS servers on UDP port 53. ### Device DNS Verify that the user's device is not configured to use [Private DNS](/v1/docs/device-dns-v7-0), which can override match domain settings set by AppGate ZTNA. --- ## Diagnose DNS issues If a user has an entitlement for a protected host but cannot access it, the issue is likely DNS-related. On the Gateway, check the DNS server IP addresses used by the [appliance](/v1/docs/adding-a-new-appliance-v7-0#system-settings), the DNS resolver, and the [DNS forwarder](/v1/docs/configuring-sites-v7-0#dns-forwarding). The examples below use DNS Forwarder IPv4 address 100.127.20.30 (generated when the DNS forwarder was configured) and forward DNS queries to DNS server 10.10.10.10. If the Gateway cannot resolve the protected host, device DNS resolution will also fail. ### Check the Gateway's DNS On the Gateway, run: `dig github.com @10.10.10.10` Replace `10.10.10.10` with the IP address of your DNS server. Check the response for `NOERROR`. A `NXDOMAIN` status means no DNS record exists for the protected host: ```plaintext ;; Got answer: ;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 14058 ``` Then verify the IP address in the answer section: ```plaintext ;; ANSWER SECTION: github.com.    50    IN    A    140.82.121.4 ``` ### Check the DNS resolver and DNS forwarder on the Gateway #### DNS resolver On the Gateway the user is connected to, run: `sudo cz-names status` Check the list of resolutions: `dns://siteexample.com: ipv4, ipv6` There is typically one entry for each protected host (defined in the entitlement action) that signed-in users can access. For more information, run: `sudo cz-console -d cz-gonamed -p` This provides resolver process information for each configured resolver, including hits, misses, insertions, and eviction counts; the update interval; and cache and configuration details such as: ```plaintext Status: healthy Update interval: 1m0s Match domains: [internal.company.com] Zones transfers: false AAAA lookups: true Hostnames: 1 ``` Check `cz-gonamed.log` on the Gateway for the name being resolved and the resulting IP addresses. #### DNS forwarder On the Gateway the user is connected to, run: `sudo cz-console -d cz-dnsfwd -p` Check for registered rules: `rules registered = 2` The number must match the number of match domains configured in the signed-in user’s DNS policy. Check for matched rules: `*.example.com: tun IPs` There is typically one entry for each protected host (entitlement action) that each user (tun IP) has attempted to access. Check `cz-dnsfwd.log` for: ```plaintext INFO    [wildcard][total-added=1][total-removed=0] Updating domain rules INFO    [wildcard][rule=*.bla.bla.com] Domain rule added ``` ### Check DNS on the connecting device DNS behavior differs across operating systems. Two users with identical policies and entitlements but different operating systems may have different access—often because of these DNS differences. For example, macOS uses the built-in match domain concept. Windows uses the Name Resolution Policy Table (NRPT), which Windows treats separately from standard DNS server configuration. Windows checks the NRPT before sending a DNS query. If a query matches an NRPT entry, Windows handles it according to the table settings; otherwise, Windows uses the configured DNS servers. If the hostnames in entitlements are not resolving correctly, use the checks below. #### **Basic DNS check (all platforms)** If a protected host is unreachable through an entitlement, first try connecting using the host's IP address instead of its DNS name. The most reliable cross-platform method for checking DNS resolution is `ping`. Ignore whether the ping succeeds or fails—check only the resolved IP address. > [!NOTE] > **NOTE** > > Do not use `nslookup` to check AppGate ZTNA DNS configurations. On both macOS and Windows, `nslookup` bypasses the OS resolver and has no awareness of AppGate ZTNA DNS policies. ### Check DNS when a DNS policy is configured #### Windows Standard DNS commands are not appropriate when NRPT is in use. To check DNS resolution, use the `Resolve-DnsName` cmdlet, which supports parameters that customize DNS queries. To check NRPT settings, run: `Get-DnsClientNrptPolicy -Effective` In the output, locate the namespace you need and verify that the name server IP address is correct. A correct entry confirms that all requests for that namespace—for example, `.github.com`—are sent to the DNS forwarder at `100.127.20.30`. ![Configuration settings for DirectAccess, including DNS servers and encryption options.](https://cdn.us.document360.io/e7482ce5-acfa-4c3b-b76c-b6c32472644a/Images/Documentation/ag55-nrpt_policy.png?sv=2026-02-06&spr=https&st=2026-11-21T21%3A49%3A38Z&se=2026-11-21T22%3A49%3A38Z&sr=b&sp=r&sig=FVNa31hf1Hy9irtwVmEN1TqZ8TwkfHOHspYN2AgQ77U%3D) > [!NOTE] > **NOTE** > > `ipconfig /all` does not display NRPT entries added by AppGate ZTNA. Windows treats NRPT entries differently from standard DNS server configurations.. #### macOS To check DNS resolution, run: `dscacheutil -q host -a name myapp.myco.com` Expected output: ```plaintext name: myapp.myco.com ipv6_address: fd00:ffff:a:1:2:3:4:5 name: myapp.myco.com ip_address: 10.10.10.10 ``` To check DNS settings, run: `scutil --dns` In the output, locate the domain you need and verify that the nameserver IP address is correct. A correct entry confirms that all requests for that domain—for example, `.github.com`—are sent to the DNS forwarder at `100.127.20.30`. ![DNS resolver output showing domain, nameserver, flags, and reachability status.](https://cdn.us.document360.io/e7482ce5-acfa-4c3b-b76c-b6c32472644a/Images/Documentation/ag55-scutil.png?sv=2026-02-06&spr=https&st=2026-11-21T21%3A49%3A38Z&se=2026-11-21T22%3A49%3A38Z&sr=b&sp=r&sig=mq3lkgNRH1rCWoGTgH7BHObdOCIyAv7MGCM5cL4F7rY%3D) ### Check the client logs [Download and unzip the client logs](/v1/docs/status-rights-and-logs-v7-0). Open `driver.log` and search for `DNS domain`. You should find entries for each protected host: `Info : DNS domain: github.com --> 100.127.20.30` On Windows, you should also find entries for each NRPT record added: `Info : Added DNS policy entry: .github.com = 100.127.20.30` These entries confirm that the client is aware of the DNS policy and has applied the DNS configuration. ### Check Portal user's DNS The Portal includes a DNS proxy service that ensures each user receives the DNS policy and entitlement configured for them. > [!NOTE] > **NOTE** > > The Portal requires a default DNS server. To view the live cache—which maps users to their client IDs and DNS settings—run the following on the Portal: `sudo cz-memcachedump` The output lists: client id, username, status, DNS servers, and DNS domains. Because this is a live cache view, results may be incomplete on the first run. Run the command more than once if needed. Find the username and verify that the DNS servers are correct. --- ## Check access issues At this point, assume DNS is working correctly. If the user still cannot access protected hosts, use the checks below. ### User access rights Only assigned policies provision entitlements to the user. Use `dns://` syntax for the DNS resolver or `*.domain.com` syntax for the DNS forwarder. [Download the client logs](/v1/docs/status-rights-and-logs-v7-0) from the client's **About** screen. In `log.log`, verify the following: - The user has the required entitlements: `Info : Entitlements for 'Site': app1, app2, app3` - Any conditions have been resolved successfully: ```plaintext Info : Activate remedy. Info : Sending OTP pin to controller. RemedyProperties: 'ClaimSuffix , ProviderId , EntitlementName , State: '', Timeout: '0' Info : Successfully got a new claims token with OTP for . ``` ### Routes The client’s **About** screen displays the assigned IP address of the tun adapter. Use this to verify which IP addresses route through the tunnel. **Windows**: Run `netstat -rn` and verify that the network destination routes to the correct interface (tun IP). **macOS**: Run `ifconfig` and find the network interface name (such as utun2) associated with the tun IP. Then run `netstat -rn` and verify that the destination routes to the correct network interface. You can also check routing in [the client logs](/v1/docs/status-rights-and-logs-v7-0). Download the logs from the **About** screen and open `driver.log`. **Windows**: `Info : [Site] route-add[37 10.10.10.10/32]: OK` **macOS**: `Info : [Site] Running 'route -n add -inet -host 10.10.10.10 -interface utun2'` > [!NOTE] > **NOTE** > > When using the DNS forwarder, routes are written only after access has been attempted. ### Portal web clients Troubleshooting Portal access requires the user's client ID. You can obtain the client ID from `cz-memcachedump` (covered in the DNS section above), from the live session information (**ClientID** field), or from `cz-webd.log`. **Option 1**: On the Portal, run: `sudo nc -U /var/run/cz-webd/cz-webd-admin.socket` Then enter: `sessions list` Example output: `ShortID: vvvvvv ClientID: xxxx SrcIP: 1.2.3.4 Dn: CN=yyyyyy,CN=<username>,OU=zzzzzz SignedIn: true` **Option 2**: Open `cz-webd.log` in the Portal logs. Search for `CN=<user>` and find the most recent matching entry: `INFO [session][clientID=xxxx][cookie=wwww][dn=CN=yyyyyy,CN=<username>,OU=zzzzzz][loggedIn=true][srcIP=1.2.3.4] Client connected` Once you have the client ID, open `cz-webclient@xxxx.log`. This file is the log record for that user's web client and contains information similar to the standard client logs. ### Gateway session If the client-side checks look correct, check the traffic through the Gateway to the protected host. In the admin UI dashboard, go to the [session details](/v1/docs/active-sessions-v7-0) for the user. Select the Site where the protected host resides and locate the entitlement. This view shows live information from the Gateway the user is currently connected to. Conditions display in green when satisfied and in red when not yet met. The firewall rules include the port type and hosts. ![Access status for various corporate services at Gothenburg site, highlighting access conditions.](https://cdn.us.document360.io/e7482ce5-acfa-4c3b-b76c-b6c32472644a/Images/Documentation/ag64-session1.png?sv=2026-02-06&spr=https&st=2026-11-21T21%3A49%3A38Z&se=2026-11-21T22%3A49%3A38Z&sr=b&sp=r&sig=yVaWwlV1UVEdey5%2BwxYeZjtEe%2BKf0lYFZJVQo1%2FOlqs%3D) For more session details, run the following on the Gateway: `vpn-logcat -S today -u <username> list` This lists all sessions for today. Select the session of interest based on the time, then run: `vpn-logcat -S today -u <username> session <time>` This filters the logs to display only the audit logs for in chronological order. For more specific information from the VPN daemon, run: `vpn-console --search-user <username>.` The output includes used entitlements, unused entitlements, and URL access details. If URL access (HTTP up action type) is in use, run the following for more information from NGINX: `curl -v` `http://127.0.0.1:9202/url_access/print_user_<tun IP>`. T Obtain the tun IP from the client’s **About** screen or from the user's session details in the system claims. --- ## Protected host health In the admin UI dashboard, go to the [session details](/v1/docs/active-sessions-v7-0) for the user. The global details at the top show the number of unreachable hosts the user has encountered. Select the Site where the problematic protected host resides to see the unreachable host count for that Site. ![User Gateway statistics for a Site, including bytes read and written over IPv4.](https://cdn.us.document360.io/e7482ce5-acfa-4c3b-b76c-b6c32472644a/Images/Documentation/ag64-session2.png?sv=2026-02-06&spr=https&st=2026-11-21T21%3A49%3A38Z&se=2026-11-21T22%3A49%3A38Z&sr=b&sp=r&sig=qWsIJFthAMqr87loQCOzP8PNFUMSoKIe%2BXBegKw4TQw%3D) If the user has experienced unreachable hosts, see [App Health Reports](/v1/docs/app-health-reports-v7-0) for more details.