Diagnostics and common issues

This section helps you quickly work through Qarvix problems: a device doesn't show up online, the WSS channel won't establish, the WireGuard handshake isn't refreshing, there's a VPN IP but no access, LAN/API is unreachable over the tunnel, or a user doesn't see the site they need.

The approach is simple: check layer by layer, from general to specific, and don't reinstall the agent before checking the network, routes, ACL, and logs.

In short

• First determine the member type: managed device or static client.
• Check the organization and network.
• Check online status, Last seen, and the logs.
• For a managed device, check WSS and WireGuard separately.
• For a static client, look at the freshness of the WireGuard handshake.
• If LAN/API is unreachable, check the subnet route, ACL, firewall, and address plan.
• When contacting support, gather symptoms, timing, the device, the network, and logs.

Basic diagnostic order

1. Find the organization.
2. Open the right network.
3. Find the member.
4. Check the VPN IP.
5. Check online/offline and Last seen.
6. Open the device log.
7. Check the audit log for the period of the issue.
8. Check routes, ACL, and peer mesh.
9. Check reachability of the local device or API.
10. Record the time, symptoms, and results of the checks.

If the problem is intermittent, exact dates and times matter especially. Without them, it's hard to match the log against the complaint.

Device doesn't show up in the list

Symptoms

• a token was created, but the device doesn't show up;
• the engineer reports the agent is installed;
• there's no new node in the device list;
• the audit log shows token generation but no connection.

Possible causes

• the token expired;
• the token was already used;
• the wrong network was selected;
• the device has no access to the control plane;
• DNS isn't working;
• the TLS connection doesn't establish;
• the device's clock is significantly off;
• a firewall is blocking WSS.

What to check

• the token's expiry;
• the correct organization and network;
• the device's access to the Qarvix server;
• DNS at the site;
• the device's clock;
• agent logs;
• the audit log.

If the token expired or was already used, create a new one. Don't try to reuse the old token.

WSS channel won't establish

WSS is needed by a managed device for commands, configuration, and heartbeats.

Symptoms

• the device isn't receiving configuration;
• the heartbeat isn't refreshing;
• the agent doesn't come online;
• WebSocket connection errors in the logs;
• WireGuard isn't getting up-to-date settings.

Possible causes

• the control plane endpoint is unreachable;
• HTTPS/WSS is being blocked;
• a TLS error;
• the device's clock is wrong;
• a proxy or firewall is dropping the connection;
• the token or agent credentials are wrong.

What to check

• reachability of the server address from the device;
• DNS;
• time and time zone;
• the TLS certificate;
• firewall rules;
• agent logs;
• the device log in Qarvix.

If WSS isn't working, a managed device won't be able to reliably receive commands and configuration updates.

WireGuard handshake isn't refreshing

The WireGuard handshake shows that a member has recently exchanged encrypted traffic.

Symptoms

• the device or client looks offline;
• there's a VPN IP but no traffic;
• a static client hasn't updated its status in a while;
• the hub doesn't see a fresh handshake.

Possible causes

• UDP is blocked;
• the keys are wrong;
• the endpoint is incorrect;
• an AllowedIPs conflict;
• the device isn't sending traffic;
• a firewall is blocking WireGuard;
• the external address or NAT state changed.

What to check

• UDP access to the hub;
• the WireGuard configuration;
• the keys;
• AllowedIPs;
• whether there's outbound traffic from the client;
• the firewall on the client and at the site;
• the device log or hub state.

For a static client, a missing fresh handshake doesn't always mean an outage. Sometimes the client simply hasn't sent traffic.

There's a VPN IP, but no access

Symptoms

• the member is online;
• a VPN IP has been issued;
• a ping or connection to the target address doesn't go through;
• the device's web/API is unreachable.

Possible causes

• ACL is denying the direction;
• a subnet route hasn't been added;
• peer mesh is off;
• a firewall on the router is blocking forwarding;
• the local device isn't responding;
• there's no return route;
• subnets overlap;
• the wrong address or port was chosen.

What to check

1. Whether the router's VPN IP responds to a ping.
2. Whether there's a route to the LAN.
3. Whether ACL allows the direction you need.
4. Whether peer mesh is on, if direct access is needed.
5. Whether the router's firewall passes traffic into the LAN.
6. Whether the local device is reachable from the LAN itself.
7. Whether the VPN CIDR overlaps with the LAN subnet.

If the VPN IP is reachable but the LAN isn't, the problem is most often in the route, ACL, or firewall.

LAN subnet isn't working

Symptoms

• the router is online;
• the router's VPN IP is reachable;
• devices on the LAN don't open;
• the API behind the router is unreachable.

Possible causes

• a subnet route hasn't been added;
• the route was added to the wrong gateway;
• the local subnet is specified incorrectly;
• the router's firewall denies forwarding;
• the local device uses a different gateway;
• the address subnet overlaps with the user's network;
• ACL denies access.

What to check

• the LAN CIDR is correct;
• the gateway device;
• the routing table;
• the firewall;
• device reachability from the LAN;
• ACL;
• the agent's configuration-apply log.

Device API is unreachable over the tunnel

Symptoms

• there's a LAN route;
• the device pings or is partially reachable;
• the web/API doesn't open;
• the integration gets a timeout or connection refused.

Possible causes

• the wrong port;
• the service listens only on the local interface;
• a local firewall is blocking the port;
• the API requires HTTPS or separate authorization;
• ACL allows ICMP but not the TCP/UDP you need;
• the device is reachable only from certain addresses;
• the device's certificate isn't trusted.

What to check

• the API's IP and port;
• API reachability from the site's LAN;
• the protocol - HTTP/HTTPS/RTSP/Modbus or another;
• the local firewall;
• ACL by port;
• API credentials;
• integration logs.

A user doesn't see a site

Symptoms

• the device exists, but the user doesn't see it;
• the user sees the organization but not the network;
• access was granted, but the site is unreachable.

Possible causes

• the user is in a different organization;
• the user's role isn't bound to the right network;
• the role doesn't allow viewing devices;
• a contractor's access was revoked;
• the user logged in through the wrong account or SSO group.

If a device isn't showing up in the dashboard, it's not about ACL: ACL determines where a member's traffic can reach, not what a user sees in the interface. Visibility is determined by the organization, the role, and which networks it's bound to.

What to check

• the user's organization;
• the role and the networks it's bound to;
• SSO groups, if OIDC is used;
• the audit log;
• access rules;
• account activity.

Connection token doesn't work

Symptoms

• the agent reports a registration error;
• the device doesn't show up;
• the token is entered again;
• the token was sent a while ago.

Possible causes

• the token expired;
• the token was already used;
• the token was created for a different network;
• the token was copied incorrectly;
• the device can't reach the server.

What to do

• check the expiry;
• create a new token;
• make sure the right network is selected;
• hand the token only to the responsible engineer;
• check WSS access from the device.

Issues after an ACL change

Symptoms

• access worked and disappeared after a rule change;
• part of a group's devices lose access while others keep working;
• monitoring stopped receiving data.

Possible causes

• a rule became too strict;
• a permission to the LAN subnet was forgotten;
• the device isn't in the rule's target group;
• the rule was applied to the wrong network;
• default access denies the direction.

What to check

• the audit log;
• the last ACL change;
• which group the device belongs to;
• which addresses and ports are allowed;
• which rules apply first;
• whether there's a separate rule for the API or LAN.

What to attach for support

So support can start without a long back-and-forth, attach:

• the organization;
• the network name;
• the device or client name;
• the VPN IP;
• the LAN subnet, if it's a route issue;
• the API address and port, if it's a device-behind-router issue;
• the exact time of the issue;
• a screenshot of the status;
• a snippet of the device log;
• a snippet of the audit log;
• what's already been checked;
• expected vs. actual result.

If the issue involves a router, add the model, firmware, and agent version.

Quick symptom table

Diagnostic checklist

• The member type has been determined.
• The organization and network have been checked.
• The VPN IP was issued correctly.
• Online/offline was read with the member type in mind.
• WSS was checked for a managed device.
• The WireGuard handshake was checked for a client.
• The subnet route was checked for LAN access.
• ACL was checked for the direction you need.
• The firewall and the site's local network were checked.
• Logs are attached to the support request.

Related sections

• Devices and VPN addresses - member types and statuses.
• Networks, routes, and ACL - routes, peer mesh, and access rules.
• Device API over the tunnel - diagnosing local APIs.
• Logs and reports - where to look for events and changes.
• Offline deployment - the specifics of closed meshes.