/

Common Issues

Connection Problems

Client Cannot Connect to Gateway

Symptoms: The client shows "Connection timed out" or "Gateway unreachable" after clicking Connect.

Diagnosis:

  1. Verify network connectivity — can the client reach the internet?
  2. Check that the gateway endpoint is reachable: 
    # Test UDP connectivity to gateway
nc -zu gateway.yourdomain.com 51820
  3. Check firewall rules — ensure outbound UDP traffic is permitted
  4. Verify the gateway is healthy in the admin interface under Gateway Pools

Common Causes:

  • Corporate firewall blocking UDP traffic (try port 443 if configured)
  • Gateway container not running — check docker ps on the gateway host
  • DNS not resolving the gateway hostname
  • Client has a stale gateway directory — disconnect and reconnect to force a refresh

Connection Drops Frequently

Note: This section will be fully applicable once native client applications are released. For now, these diagnostics apply to development/testing environments.

Symptoms: The VPN connects but drops every few minutes.

Diagnosis:

  1. Check client logs for disconnect reasons
  2. Monitor gateway logs for session termination events
  3. Check if the kill switch is preventing reconnection

Common Causes:

  • NAT timeout on the network path — AWT keepalives should prevent this, but aggressive NAT devices may still cause issues
  • Mobile device battery optimization killing the VPN service (Android)
  • Network switching (Wi-Fi to cellular) — AWT supports connection migration, but some networks block resumed sessions
  • Gateway overloaded — check session counts in the admin interface

Slow Tunnel Performance

Symptoms: Traffic through the VPN is noticeably slower than direct internet.

Diagnosis:

  1. Test speeds both through the tunnel and directly
  2. Check the gateway's CPU and memory usage
  3. Check the admin interface for throughput metrics

Common Causes:

  • Gateway node undersized for the number of concurrent users — refer to the capacity model
  • High anti-fingerprinting profile (medium or high) adds padding and cover traffic overhead
  • PQ re-randomization set to aggressive increases CPU load
  • MTU mismatch — the gateway should auto-detect MTU, but misconfigured network equipment can cause fragmentation

Enrollment Problems

Enrollment Token Rejected

Symptoms: Client shows "Invalid or expired enrollment token" during enrollment.

Diagnosis:

  1. Check the token status in admin interface under Enrollment Tokens
  2. Verify the token has not expired
  3. Verify the token has not already been redeemed (if single-use)

Resolution:

  • Generate a new token if the current one has expired
  • If the token shows as "redeemed" but the device did not complete enrollment, the enrollment may have partially failed — revoke the token and generate a new one
  • Ensure the client is connecting to the correct control plane URL

Enrollment Succeeds but Connection Fails

Symptoms: Device enrolls successfully but cannot establish a VPN connection.

Diagnosis:

  1. Check that at least one gateway pool is configured and healthy
  2. Check that the device's user has an applicable policy
  3. Check the policy's minimum authentication mode — the device may not meet the requirements

Resolution:

  • Ensure a gateway pool exists with endpoints configured
  • Assign a policy to the user's group or tenant
  • Verify the authentication mode compatibility

"Entitlement Exceeded" During Enrollment

Symptoms: Enrollment fails with "Device limit reached" or "User limit reached".

Resolution:

  • Check your plan's device and user limits in the admin interface
  • Remove or revoke unused devices to free capacity
  • Upgrade your plan to increase limits

Policy Problems

Policy Not Applied to Client

Symptoms: Client connects but does not seem to follow the expected policy (wrong tunnel mode, wrong DNS, etc.).

Diagnosis:

  1. Check the policy assignment in the admin interface — is a policy published for the user's scope?
  2. Check the policy channel — is the policy published to "stable" or only "canary"?
  3. Force a policy refresh on the client (disconnect and reconnect)

Resolution:

  • Ensure the policy is published to the "stable" channel
  • Check scope precedence: device > group > tenant > global
  • If the user belongs to multiple groups with different policies, the most specific policy wins

Split Tunnel Routes Not Working

Symptoms: Traffic to specific networks is not routed through the tunnel in split tunnel mode.

Diagnosis:

  1. Review the split tunnel rules in the policy
  2. Check the CIDR notation — ensure the subnet mask is correct
  3. Check the default access setting — if "deny", only explicitly allowed routes go through the tunnel

Resolution:

  • Verify the CIDR, protocol, and port in each split tunnel rule
  • Test with a broader CIDR (e.g., 10.0.0.0/8 instead of 10.0.1.0/24) to confirm routing works
  • Check that the client has received the latest policy version

Admin Interface Problems

Cannot Log In to Admin Interface

Symptoms: Admin login page rejects credentials.

Diagnosis:

  1. Check if the account is locked (too many failed attempts)
  2. Verify you are using the correct admin URL (/admin/ on the control plane)
  3. Check that the control plane container is running and healthy

Resolution:

  • If locked out, wait for the lockout timeout or ask another admin to unlock your account
  • If this is the first login, use the initial admin credentials set during setup
  • Check control plane logs for authentication errors

Admin Interface Slow or Unresponsive

Diagnosis:

  1. Check the control plane container's resource usage (CPU, memory)
  2. Check PostgreSQL connection pool health
  3. Check network latency between the browser and the control plane

Resolution:

  • Scale up the control plane container if resource-constrained
  • Check PostgreSQL slow query log for expensive queries
  • Ensure the admin interface is not being accessed through an unusually high-latency path

Gateway Problems

Gateway Not Appearing in Pool

Symptoms: A new gateway container is running but does not appear in the admin interface.

Diagnosis:

  1. Check gateway container logs for registration errors
  2. Verify the AW_CP_ENDPOINT environment variable is correct
  3. Check network connectivity between the gateway and the control plane

Resolution:

  • Ensure the control plane URL is correct and reachable from the gateway container
  • Check that the gateway container can resolve the control plane hostname
  • Check firewall rules between the gateway and control plane networks

Gateway Shows "Degraded" Health

Symptoms: Gateway pool status shows "degraded" in the admin interface.

Common Causes:

  • Gateway node is overloaded (CPU > 80%, memory > 90%)
  • Gateway lost connectivity to the control plane temporarily
  • Health check endpoint not responding within timeout

Resolution:

  • Scale the gateway fleet (add more nodes)
  • Check the gateway container's resource allocation
  • Review gateway logs for error patterns

Licensing Problems (Hardware Appliance)

Phone-Home Failure

Symptoms: Appliance shows "Licence validation failed" warning.

Diagnosis:

  1. Check the appliance's internet connectivity
  2. Verify DNS resolution works from the appliance
  3. Check that outbound HTTPS traffic is not blocked by a firewall

Resolution:

  • Ensure the appliance can reach licensing.aegiswire.com on port 443
  • If behind a proxy, configure the proxy settings on the appliance
  • The appliance has a 48-hour grace period — resolve connectivity within that window

Licence Expired

Symptoms: VPN operations are suspended. Admin interface shows "Licence expired".

Resolution:

  • Renew your annual licence through the AegisWire customer portal at app.aegiswire.com
  • Once payment is processed, the next phone-home check will activate the renewed licence
  • VPN operations resume automatically after successful licence validation

Getting Help

If your issue is not covered here:

  1. Export diagnostic logs from the affected component (client, gateway, or control plane)
  2. Note the exact error message and any error codes
  3. Check the audit log for related events
  4. Contact support through your support channel:

Include in your support request:

  • Your organisation ID / tenant ID
  • The affected component (client, gateway, control plane)
  • The error message and error code
  • Timestamps of when the issue occurred
  • Diagnostic log exports
  • Steps to reproduce the issue