Troubleshooting

⏱️ Session expired — can't reach resources

Sessions have a limited lifetime (typically 4–8 hours). When your session expires, the WireGuard handshake fails and you lose access to internal resources.

Symptoms:

• Ping to internal hosts times out
• TUI shows "connected" but transfer bytes stop increasing
• wireztna status shows a stale handshake (>5 minutes old)

Solution:

# The client auto-renews, but if it failed you can force it:
wireztna disconnect
wireztna connect

The connect command automatically requests a fresh session. If your login token also expired, you'll be prompted to log in again.

🔄 Connection dropped — how to reconnect

If your network changed (Wi-Fi switch, sleep/wake, laptop lid close), the tunnel may need to re-establish.

Quick fix:

# Disconnect cleanly and reconnect
sudo wireztna disconnect
sudo wireztna connect

Using the TUI:

# The TUI reconnects automatically on network changes
sudo wireztna tui
# Press 'd' to disconnect, then 'c' to reconnect

Using the tray app (Windows/macOS):

Right-click the tray icon → Disconnect → Connect. The tray app handles session renewal automatically.

💻 Switched to a new device

Each device needs its own enrollment. Your WireGuard private key is unique per device and never leaves it.

Steps:

1. Ask your admin to generate a new enrollment token for you (or generate one from the self-service portal if enabled)
2. On the new device:

   wireztna enroll "https://your-broker/api/v1/clients/enroll?token=..."
   wireztna login
   sudo wireztna connect

3. The old device will stop working once you enroll the new one (each user has one active key)

🔑 Re-enrollment from scratch

If your config is corrupted, you changed your username/email, or enrollment failed midway, you may need a clean re-enrollment.

macOS / Linux:

# 1. Remove existing config
rm -rf ~/.wireztna

# 2. Get a fresh enrollment token from your admin

# 3. Enroll again
wireztna enroll "https://your-broker/api/v1/clients/enroll?token=NEW_TOKEN"
wireztna login
sudo wireztna connect

Windows:

# 1. Remove existing config (PowerShell)
Remove-Item -Recurse -Force "$env:USERPROFILE\.wireztna"

# 2. Get a fresh enrollment token from your admin

# 3. Enroll again
wireztna enroll "https://your-broker/api/v1/clients/enroll?token=NEW_TOKEN"
wireztna login
wireztna connect

⚠️ Shows "connected" but nothing works

The tunnel interface is up, IP is assigned, but you can't reach any resources. Transfer shows 0 bytes.

Most common cause: key mismatch after re-enrollment

This happens when you enrolled twice (e.g., token error the first time) and the broker has a different public key than your local config.

Quick diagnostic:

# Check if you have a handshake
wireztna status

# If "latest handshake: never" or very old → the broker doesn't recognize your key
# Solution: clean re-enroll (see section above)

Other possible causes:

• Session expired — run wireztna disconnect && wireztna connect
• Publisher offline — ask your admin to check the publisher status
• Firewall blocking UDP — WireGuard needs outbound UDP to port 51820 (see Requirements)
• MTU issues (Windows) — update to the latest client version (fixed in v0.9.2+)

🌐 Internal DNS not resolving

You can ping IPs but internal hostnames (e.g., db.compute.internal) don't resolve.

Check your DNS configuration:

# macOS — verify resolver is registered
scutil --dns | grep -A3 "compute.internal"

# Linux — check systemd-resolved
resolvectl status | grep -A3 "wireztna"

# Windows — check NRPT rules
Get-DnsClientNrptRule | Where-Object { $_.DisplayName -like "WireZTNA:*" }

Common fixes:

• Reconnect — DNS rules are applied on connect. Disconnect and connect again.
• macOS: dig/nslookup don't work — This is expected. These tools bypass macOS resolvers. Use dig @10.200.0.1 hostname.zone to test explicitly, or just use ping hostname.zone which uses the system resolver.
• Zone not configured — Ask your admin if the DNS zone is configured on the publisher.

🖥️ Tray app won't connect (Windows)

The tray icon shows but clicking "Connect" does nothing or shows an error.

Common causes and fixes:

• UAC not accepted: The helper process needs elevation. When you click Connect, you should see a UAC prompt. If you dismissed it, try again.
• Helper already running: Check Task Manager for wireztna.exe processes. Kill them all and retry.
• Not enrolled: Open a terminal and run wireztna status. If it says "not enrolled", you need to enroll first.
• Antivirus blocking: Some antivirus (Kaspersky, ESET) block the wintun driver. Add wireztna.exe to exclusions.

Manual connection as fallback:

# Open PowerShell as Administrator
wireztna connect

# If this works but the tray doesn't → tray/helper IPC issue
# Restart the tray app from Start Menu

🔀 Switching between projects / groups

If you belong to multiple groups that have overlapping networks, you may need to select which project to route through.

Using the CLI:

# Select a specific project
sudo wireztna connect -g project-name

# Or select "all" to access everything (with potential routing ambiguity)
sudo wireztna connect -g all

Using the TUI:

# Open TUI
sudo wireztna tui

# Press Tab → Projects tab
# Press 0 for "All groups" or 1-9 to select a project
# Press 'c' to connect with the selection

Switching projects forces a session renewal. Your old session is deactivated and a new one is created with the correct routing rules.

🌍 Exit node / VPN mode not working

If your admin enabled VPN mode for your account, you can route all traffic through a publisher (full tunnel).

Prerequisites:

• Your user must have vpn_mode = true (admin enables this)
• At least one publisher must be marked as an exit node
• That publisher must be in a group assigned to you

Connecting in VPN mode:

# CLI — specify exit node
sudo wireztna connect --exit-node publisher-name

# TUI — the Projects tab shows exit nodes when VPN mode is enabled
# Select the location and press 'c'

# To switch back to split tunnel:
sudo wireztna connect --split

If VPN mode connects but internet doesn't work:

• Check that the publisher has internet access (it needs to masquerade your traffic)
• Try a different exit node location if available
• Verify with wireztna status that the handshake is fresh

✅ How to check your connection status

The quickest way to diagnose what's happening:

# Quick status check
wireztna status

# Output shows:
#   Enrolled: yes/no
#   Tunnel: up/down
#   Overlay IP: 10.200.x.x
#   Handshake: Xs ago (should be < 150s)
#   Transfer: rx / tx bytes (should increase)
#   Session: active / expired
#   Project: project-name or "all"

What to look for:

🪟 Windows

Complete uninstall (before updating or troubleshooting)

# 1. Disconnect the tunnel (if connected)
wireztna disconnect

# 2. Remove NRPT DNS rules (PowerShell as Admin)
Get-DnsClientNrptRule | Where-Object { $_.DisplayName -like "WireZTNA:*" } | Remove-DnsClientNrptRule -Force

# 3. Uninstall the MSI (PowerShell as Admin)
# Option A: via Settings → Apps → WireZTNA → Uninstall
# Option B: via command line
msiexec /x "{PRODUCT-CODE}" /quiet
# Or find it by name:
Get-WmiObject Win32_Product | Where-Object { $_.Name -like "*WireZTNA*" } | ForEach-Object { $_.Uninstall() }

# 4. Remove user config (optional — only if doing clean re-enrollment)
Remove-Item -Recurse -Force "$env:USERPROFILE\.wireztna"

# 5. Kill any lingering processes
Get-Process wireztna* -ErrorAction SilentlyContinue | Stop-Process -Force

Update to a new version

# 1. Disconnect first
wireztna disconnect

# 2. Install the new MSI (overwrites the old version)
msiexec /i wireztna-X.Y.Z-windows-amd64.msi /quiet

# 3. Reconnect
wireztna connect

# Your config (~\.wireztna\config.yaml) is preserved across updates.
# No need to re-enroll.

Verify the installation

# Check version
wireztna --version

# Check the tunnel adapter
Get-NetAdapter | Where-Object { $_.InterfaceDescription -like "*wintun*" -or $_.Name -like "*wireztna*" }

# Check active NRPT rules (split DNS)
Get-DnsClientNrptRule | Where-Object { $_.DisplayName -like "WireZTNA:*" }

# Check helper process is running
Get-Process wireztna -ErrorAction SilentlyContinue

Known Windows issues

• SmartScreen warning on first install: The MSI may show "Windows protected your PC". Click "More info" → "Run anyway". This disappears once we have an EV code signing certificate.
• Antivirus quarantines wireztna.exe: Add an exclusion for C:\Program Files\WireZTNA\ in your antivirus.
• UAC prompt every time you connect: This is by design — the helper needs elevation to create the tunnel adapter. Add your user to the "Network Configuration Operators" group via GPO to avoid it.
• wintun.dll error: Update to the latest MSI (v0.9.2+). Older versions required a separate WireGuard installation.

🍎 macOS

Install

# Prerequisites: wireguard-go and wireguard-tools
brew install wireguard-go wireguard-tools

# Download the binary for your architecture (Intel or Apple Silicon)
# From your admin's downloads page or:
curl -fsSL https://your-broker/downloads/wireztna-darwin-arm64 -o /usr/local/bin/wireztna
chmod +x /usr/local/bin/wireztna

Complete uninstall

# 1. Disconnect
sudo wireztna disconnect

# 2. Remove the binary
sudo rm /usr/local/bin/wireztna

# 3. Remove split DNS resolver files
sudo rm -f /etc/resolver/compute.internal  # repeat for each zone

# 4. Remove user config (optional — only if doing clean re-enrollment)
rm -rf ~/.wireztna

Update to a new version

# 1. Disconnect
sudo wireztna disconnect

# 2. Replace the binary
curl -fsSL https://your-broker/downloads/wireztna-darwin-arm64 -o /usr/local/bin/wireztna
chmod +x /usr/local/bin/wireztna

# 3. Reconnect
sudo wireztna connect

# Config is preserved. No re-enrollment needed.

Known macOS issues

• "cannot be opened because the developer cannot be verified": Right-click → Open → Open. Or: xattr -d com.apple.quarantine /usr/local/bin/wireztna
• dig/nslookup don't resolve internal names: Expected — these tools bypass macOS resolvers. Use ping hostname.zone or dig @10.200.0.1 hostname.zone.
• Requires sudo for every connect: macOS needs root to create network interfaces. A privileged helper daemon (auto-sudo) is planned for a future version.

🐧 Linux

Install

# Download the binary
curl -fsSL https://your-broker/downloads/wireztna-linux-amd64 -o /usr/local/bin/wireztna
chmod +x /usr/local/bin/wireztna

# Optional: allow running without sudo (one-time)
sudo setcap 'cap_net_admin+ep cap_net_raw+ep' /usr/local/bin/wireztna

Complete uninstall

# 1. Disconnect
sudo wireztna disconnect

# 2. Remove WireGuard interface (if still present)
sudo ip link del wg-wireztna 2>/dev/null

# 3. Remove the binary
sudo rm /usr/local/bin/wireztna

# 4. Clean up systemd-resolved split DNS (if applicable)
sudo resolvectl revert wg-wireztna 2>/dev/null

# 5. Remove user config (optional — only if doing clean re-enrollment)
rm -rf ~/.wireztna

Update to a new version

# 1. Disconnect
sudo wireztna disconnect

# 2. Replace binary
sudo curl -fsSL https://your-broker/downloads/wireztna-linux-amd64 -o /usr/local/bin/wireztna
sudo chmod +x /usr/local/bin/wireztna

# 3. Re-apply capabilities if using rootless mode
sudo setcap 'cap_net_admin+ep cap_net_raw+ep' /usr/local/bin/wireztna

# 4. Reconnect
sudo wireztna connect

# Config is preserved. No re-enrollment needed.

Known Linux issues

• sudo resets HOME to /root: Fixed in v0.4.5+. If using an older version, run sudo -E wireztna connect to preserve your home directory.
• WireGuard kernel module not loaded: On some distributions, run sudo modprobe wireguard first. Kernel 5.6+ has WireGuard built-in.
• systemd-resolved not available: On systems without systemd-resolved (Alpine, older Debian), split DNS won't work automatically. Add DNS entries manually to /etc/resolv.conf or use resolvconf.
• Permission denied without sudo: Apply capabilities: sudo setcap 'cap_net_admin+ep cap_net_raw+ep' /usr/local/bin/wireztna