Ctrlk
Portal
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Tracker Failure Diagnostic Guide

A complete reference for IT administrators: understand why the We360 tracker stops running or fails to capture data, and how to resolve each scenario.

Audience: IT administrators, system owners, and support engineers responsible for managing We360 agent deployments.

The We360 tracker is a background agent that runs continuously on employee machines. When it fails to start, stops mid-session, or captures incomplete data, the root cause almost always falls into one of six categories:

  1. Installation & file-system issues

  2. Authentication & identity failures

  3. Network, firewall, and connectivity

  4. Antivirus and endpoint-security interference

  5. Data capture subsystem failures

  6. Backend and service-side issues

Use the Quick Diagnosis Checklist first, then jump to the relevant section.

Quick Diagnosis Checklist

Run through this before doing anything else. Each step takes under two minutes.

□ Step 1 — Is the tracker process running?
    Windows (Stealth):    Task Manager → Details tab → look for svcmonitor.exe or svcrunner.exe
    Windows (Standard):   Task Manager → Details tab → look for MyZenV2.exe
    macOS (Stealth):      Activity Monitor → search "zs"
    macOS (Standard):     Activity Monitor → search "MyZenV2"
    ↳ NOT running → go to Section 1 or Section 4

□ Step 2 — Do the app files still exist on disk?
    Windows (Stealth):    C:\Program Files\zs\zs\
    Windows (Standard):   C:\Program Files\Zenstack\MyZenV2\
    macOS (Stealth):      /usr/local/zs/zs.app
    macOS (Standard):     /Applications/MyZenV2.app
    ↳ Files missing → antivirus quarantined them → go to Section 4

□ Step 3 — Can the machine reach We360 servers?
    Open Desktop Doctor → Net Check tab on the affected machine
    ↳ Check fails → network / firewall issue → go to Section 3

□ Step 4 — Is the app on the latest version?
    Check agent version in your admin portal → Device Health tab
    ↳ Outdated → update before investigating further

□ Step 5 — Is the system clock and timezone correct?
    Wrong time causes authentication failures, punch-in failures, and data gaps
    ↳ Incorrect → fix the clock, then restart the agent

1. Installation & File-System Issues

1.1 App fails to start after installation

The agent requires access to a set of data directories at startup. If these directories cannot be created — due to permission restrictions, a full disk, or a locked parent folder — the tracker cannot run at all.

Symptoms

  • App is installed but never appears in Task Manager / Activity Monitor

  • No log files exist in the log path

  • Double-clicking the app icon does nothing or shows a brief error flash

Common causes

Cause
What to check
Fix

Insufficient write permissions

Can the logged-in user write to %APPDATA% (Windows) or ~/Library/Application Support (macOS)?

Run the installer as administrator (Windows) or check macOS user account type

Disk full or near-full

Free disk space on the system drive

Free at least 500 MB and restart the app

Antivirus blocking directory creation

AV quarantine log

See Section 4

Previous installation left corrupt files

Files from old version are locked or inaccessible

Run ZenCleanup.exe (Windows) or delete old app data folders (macOS), then reinstall

Before reinstalling, always run ZenCleanup.exe on Windows or delete the old application support folders on macOS. Installing on top of a broken installation rarely works.

Step-by-step resolution

1

Confirm the app is not already running

On Windows, open Task Manager → Details tab. On macOS, open Activity Monitor. Search for svcmonitor, svcrunner, or zs. If found, end those processes before reinstalling.

2

Clean up previous installation files

Download ZenCleanup.exe from Download Links & Utilities and run it as administrator.

3

Reinstall from the correct source

Download the installer from your admin portal or from docs.we360.ai. Never use we360.ai/downloads — that page may serve outdated builds that are 10 MB larger than the correct installer.

Stealth deployment: Do not rename the installer file. The filename encodes your tenant key — renaming it will cause a silent failure where the agent runs but captures no data.

4

Run with elevated privileges

Right-click the installer → Run as administrator

5

Verify log files are created

After installation, check the log directory. If log files appear within 60 seconds, the tracker started successfully.

Log paths are listed in the Log File Locations section.

1.2 Stealth agent not creating a user profile

Applies to: Stealth deployment only. Skip this section if you are running the standard (visible) desktop app.

The stealth agent requires a configuration file (keyconfig.json) embedded in the installer filename. If this file is missing or the installer was renamed, the agent starts but cannot identify which tenant it belongs to and will not create a user profile.

Symptoms

  • Agent process is running in Task Manager

  • No user appears in the admin portal

  • No data is captured

  • Log directory may not exist

The single most common cause: the installer filename was renamed.

The stealth installer filename encodes the tenant key. Renaming it strips that information and the agent cannot connect to the correct tenant.

Never rename the stealth installer. Share the file exactly as downloaded. If a client's IT team renames it "setup.exe" or similar, reinstall from the original filename.

Checklist

If the keyconfig is missing: Re-download the installer from the admin portal (using the exact original filename) and reinstall without renaming.

1.3 Database corruption or recovery mode

The tracker stores activity data locally in a SQLite database before syncing to the server. If this database becomes corrupted (due to a power loss, disk error, or abnormal shutdown), the tracker automatically attempts to recover. During recovery, data capture may pause for several minutes.

Symptoms

  • Data was flowing normally, then stopped for 5–30 minutes

  • Data resumed later but there is a gap in the timeline

  • The tracker appears to have restarted itself

What actually happens: The tracker detects sustained database errors, renames the corrupted database file (keeping it for inspection), creates a fresh database, and re-imports any in-memory events from a recovery file. This is automatic and does not require IT intervention in most cases.

When to escalate: If data capture does not resume within 30 minutes after an apparent restart, or if the same gap recurs multiple times per week, collect the logs from the device and open a support ticket. The recovery system is robust, but persistent disk-level errors warrant investigation.

2. Authentication & Identity Failures

The tracker authenticates with We360 servers using a token that is refreshed automatically. Failures in this flow prevent data from being transmitted even when the tracker appears to be running.

2.1 Token expiry and re-authentication

Symptoms

  • App running, but no data reaching the dashboard for 2+ hours

  • User receives an unexpected logout notification from the desktop app

  • Standard (non-stealth) users may see a re-login prompt

Cause: The authentication token could not be refreshed. This happens when:

  • The machine was offline for an extended period and the token expired before connectivity was restored

  • The user's account was deactivated while the app was running

  • A network proxy or DLP tool is blocking authentication requests to auth.in.we360.ai

Resolution:

Situation
Action

Standard app user

Ask the user to log out and log back in to the desktop app

Stealth agent

Restart the agent service (or the machine). The agent will re-authenticate automatically on next start

All users on a machine affected

Suspect a network/proxy issue — see Section 3

2.2 User account deactivated while agent is running

Applies to: Stealth deployment only. The standard desktop app does not auto-stop when an account is deactivated — the user will see a sign-in prompt instead.

Symptoms:

  • Agent stops capturing data mid-day with no apparent crash

  • Multiple users across a tenant lose data simultaneously

  • The agent process may no longer be visible in Task Manager

What happens: The stealth service monitor periodically checks whether the user is still active in the We360 system. If the account has been deactivated — either manually, through a bulk operation, or due to a backend issue — the service monitor receives this signal and stops the tracker for that user.

Resolution:

  1. In the admin portal, verify the affected user's account status. Re-activate if deactivated in error.

  2. Restart the machine or the agent service to resume tracking.

If many users across your organization suddenly show no data, check for a bulk deactivation event in the admin portal before restarting individual machines. Restarting machines while accounts remain deactivated will not restore data capture.

2.3 Token claims mismatch (403 errors in sync)

Applies to: Standard app only. Stealth agents re-authenticate automatically on restart — see Section 2.1 for stealth resolution.

Symptoms:

  • App appears to be running normally

  • Data visible in the local database (Desktop Doctor DB Check shows activity)

  • Data not appearing in the dashboard

Cause: The app holds a valid login token but something in the account configuration changed (such as a tenant migration). Logging out and back in issues a fresh token.

Resolution:

  1. Ask the user to log out fully and log back in to the desktop app.

  2. If the problem recurs: escalate with the device hostname, username, and approximate time the issue started.

3. Network, Firewall, and Connectivity (For We360 India Cloud)

The URLs and paths mentioned here are only for tenants running on We360 India Cloud Version. You may be hosted on other URLs and endpoints. Please check with We360 support if doubtful.

3.1 Required domains and ports

The tracker must reach the following endpoints. All connections are outbound HTTPS (port 443). No inbound connections are required.

Domain
Purpose

api.in.we360.ai

Data sync, event upload, settings

auth.in.we360.ai

Token authentication and refresh

origin.in.we360.ai

Tenant registration and identity

live.in.we360.ai

Live stream (WebSocket, port 443)

Quick test: Run Desktop Doctor's Net Check on the affected machine. If all checks pass, the machine can reach We360 servers. If checks fail, there is a firewall or network routing issue.

3.2 Firewall and proxy configuration

Corporate firewalls: If your organization uses a next-generation firewall with application control, ensure that the above domains are on the allowlist. Some firewalls classify the tracker's API traffic as "unknown" or "custom application" and block it silently.

SSL/TLS inspection (DLP/MITM proxies): If your firewall or proxy performs SSL inspection (also called TLS decryption or MITM inspection), We360 agent traffic must be excluded from inspection. The agent validates the server certificate chain and will reject connections where the certificate has been replaced by a proxy. This manifests as the agent appearing to run but failing to sync any data.

Ask your network team to add a bypass rule for *.in.we360.ai in SSL inspection policies.

VPN: If employees connect through a corporate VPN, ensure that We360 traffic is routed correctly. Split-tunnel VPN configurations may inadvertently block traffic to We360 domains if the VPN routing table does not include them. Ask your network team to verify that *.in.we360.ai is reachable both with and without VPN connected.

3.3 DNS resolution failures

Symptoms:

  • Health URL fails in the browser

  • ping api.in.we360.ai returns "could not find host" or similar

  • Internet generally works (other sites load)

Cause: DNS-level blocking by security software, DNS filtering appliances (Cisco Umbrella, Zscaler, etc.), or misconfigured split-DNS in VPN.

Resolution:

  1. On Windows, open Command Prompt and run ipconfig /flushdns, then re-run the Desktop Doctor Net Check.

  2. If DNS filtering is in use, ask your network team to allowlist *.in.we360.ai in the DNS filter.

  3. If on VPN, ask your network team to check the VPN DNS configuration.

3.4 WebSocket connectivity (live stream)

The live stream feature uses a persistent WebSocket connection. If firewalls or proxies terminate long-lived connections, users will appear offline in the live stream even while actively working.

Symptoms:

  • Users show "Offline" in the live stream despite being punched in

  • Data is still captured and synced correctly (check the dashboard — if activity data appears but live status does not, this is a WebSocket issue)

  • The problem is consistent for all users behind a specific network segment

Resolution:

  • Ask your network team to ensure WebSocket connections (HTTP Upgrade) are permitted to live.in.we360.ai on port 443.

  • WebSocket connections should not be subject to aggressive idle-timeout rules (idle timeout should be at least 60 seconds).

4. Antivirus and Endpoint Security Interference

Antivirus and endpoint detection & response (EDR) tools are the leading cause of tracker failures in enterprise environments. The tracker performs operations — monitoring running processes, capturing screenshots, recording keystrokes — that resemble behaviors that security software is designed to detect.

4.1 What AV/EDR software commonly blocks

What gets blocked
Symptom
Fix

Installer

Installation fails silently or with a generic error

Temporarily pause real-time protection during installation

App binary after installation

Files disappear from the install folder

Restore from quarantine, add folder exclusions

Process execution at runtime

Tracker starts, then stops within minutes

Add process exclusions

Network connections

Data does not sync even when app is running

Add URL exclusions

Screenshot capture system calls

Screenshots missing, tracker may crash

Add process exclusions

4.2 Required exclusions

Provide these to your IT security team for inclusion in your AV/EDR policy.

Folder exclusions (exclude from real-time scanning):

Process exclusions:

URL / domain exclusions:

4.3 Identifying AV interference

Check 1 — Are the files still there? Navigate to the installation folder. If executables or DLLs are missing after a successful installation, AV has quarantined them.

Check 2 — Check the AV quarantine log. Most AV tools maintain a quarantine or event log. Look for entries naming svcmonitor.exe, svcrunner.exe, MyZenV2.exe, or zs as quarantined or blocked items.

Check 3 — Temporarily disable real-time protection. If data capture resumes immediately after disabling AV, the AV is the cause. Re-enable it and add the exclusions from Section 4.2.

Before asking users to temporarily disable antivirus, confirm with your organization's security policy that this is permitted. Notify your security team of the exclusions being added.

4.4 Windows Defender-specific steps

  1. Open Windows Security → Virus & threat protection → Manage settings

  2. Under Exclusions, click Add or remove exclusions

  3. Add folder exclusions for the install paths listed above

  4. Add process exclusions for each executable name listed above

4.5 Reinstalling after AV quarantine

If AV has already removed files, reinstallation must follow this sequence:

1

Add AV exclusions first

Before touching the installer, add the folder and process exclusions in your AV policy. Reinstalling without exclusions in place will result in the same files being quarantined again immediately.

2

Restore quarantined files (optional)

If your AV allows restoring files from quarantine, restore all We360-related files to their original locations. This preserves any cached data on the device.

3

Run ZenCleanup.exe (Windows only)

If restoring quarantined files is not practical, run ZenCleanup.exe to remove all remnants before reinstalling.

4

Reinstall from the admin portal

Download the installer from the admin portal. Run as administrator. Verify that no AV alerts appear during installation.

5

Confirm data capture resumes

After installation, wait 15–30 minutes and verify that activity data appears in the admin portal. Monitor for at least 24 hours to confirm AV is not re-quarantining files on a delayed scan schedule.

5. Data Capture Subsystem Failures

Even when the main tracker process is running and authenticated, individual data capture components can fail independently.

5.1 Screenshot capture failures

Symptoms:

  • Activity and time data is captured, but screenshots are missing

  • Some screenshots appear but others are blank or missing

macOS requires an explicit user-granted permission for any app to capture the screen. This permission must be granted per-user and per-app install. If it is revoked (by the user, by an MDM policy, or after a system update), screenshots will stop without any visible error.

To check and restore:

  1. Open System Settings → Privacy & Security → Screen Recording

  2. If the We360 agent is not listed or is unchecked, enable it

  3. If re-enabling does not work: remove the app from the list, re-add it by clicking the + button, then restart the agent

  4. After granting permission, the agent must be restarted (or the machine rebooted) for the change to take effect

MDM-managed devices: Screen Recording permission can be pre-approved silently via a PPPC configuration profile. Contact We360 support for the configuration payload.

Linux: Screenshots on Linux require imagemagick to be installed. Run:

5.2 Browser URL and application title capture

The tracker captures the active window title and, for supported browsers, the URL. URL capture can fail if:

  • The browser extension required for certain browsers is not installed

  • A Chrome/Chromium update changes the internal session format (this has occurred in past Chrome versions and may require a tracker update)

  • The browser is running in a mode that restricts process inspection

If URLs are not being captured but other activity data is: First update the tracker to the latest version — URL capture improvements ship frequently. If the issue persists on the latest version, escalate with the browser name and version.

5.3 Tracker captures data for a while, then stops

Pattern: Data flows normally for some time (hours or days), then stops. Restarting the tracker or the machine restores data capture temporarily.

This pattern almost always indicates one of:

Cause
Distinguishing detail

AV killing the process on a scheduled scan

Data stops at the same time each day or week

Network timeout causing sync backpressure

Data stops after a network interruption and does not recover automatically

Database error causing the tracker to pause

Log files show a recovery event around the time data stopped

Memory or resource limit

Machine is under heavy load when data stops

Steps:

  1. Note the exact time data stops. Compare to AV scheduled scan times.

  2. Check logs from the period just before data stopped. If DB recovery messages are present, the device likely experienced a power event or abrupt shutdown.

  3. If AV is not the cause, collect logs using Desktop Doctor and escalate.

6. Backend and Service-Side Issues

Some tracker failures originate in the We360 backend rather than on the device. These are identifiable because they affect multiple users simultaneously or correlate with backend maintenance.

6.1 Tenant license or subscription issues

Symptoms:

  • All users in an organization simultaneously stop having data captured

  • The tracker appears to run normally on devices but nothing reaches the dashboard

  • The effect starts at a specific time and affects all users equally

Cause: If a tenant's subscription is inactive, expired, or the account has been flagged, the backend will reject all incoming data from that tenant. Devices continue to collect data locally but cannot sync.

Resolution:

  1. Log in to your admin portal. If you see a subscription warning or error banner, that is the cause.

  2. Contact We360 support with your organization's domain name to check subscription status.

  3. Once the subscription is restored, devices will automatically sync the locally-cached data that accumulated during the outage (within the local retention window).

6.2 User-level tracking restrictions

Individual users can be marked as excluded from tracking within the admin portal. When this setting is active, the backend rejects data from that user's device even though the tracker runs normally.

Symptom: One specific user has no data while all other users on the same network are unaffected.

Check: In the admin portal, navigate to the user's settings and confirm that tracking is enabled for that user.

6.3 Data pipeline delays

Symptoms:

  • Attendance and punch-in data is present, but activity data (apps, URLs, screenshots) is missing or stale

  • Data has not updated for more than 24 hours despite the tracker appearing to run normally

Understanding the pipeline: Raw activity data goes through a processing pipeline before appearing in dashboards. This pipeline can be slow during high-load periods.

What IT can do:

  • Verify the tracker is running and syncing (Desktop Doctor's DB Check will show if local data exists)

  • Run Desktop Doctor's Net Check to confirm the machine has connectivity to We360 servers

  • If local data exists and the machine has connectivity, the stall is backend-side. Escalate to We360 support with your organization domain and the date range affected.

Platform-Specific Considerations

Windows

Multi-user machines (RDP / Terminal Server): The tracker creates a separate profile for each Windows user account it runs under. On RDP servers, there is a port conflict when more than two user sessions run simultaneously. If more than two employees share an RDP server, contact We360 support for guidance on multi-session deployment.

Group Policy restrictions: Some GPO configurations prevent processes from writing to %APPDATA% or creating scheduled tasks. If the tracker cannot start after a clean installation on a managed machine, ask your domain administrator to confirm that:

  • The installation directories listed in Section 4.2 are writable by the user account that runs the tracker

  • The tracker's executable is not blocked by AppLocker or Software Restriction Policies

macOS

Required permissions: The following macOS privacy permissions must be granted to the tracker. If any are missing, the corresponding data type will not be captured:

Permission
Data affected if missing

Screen Recording

Screenshots, screen content

Accessibility

Active window title, application name

(Stealth only) Full Disk Access

Access to browser profile data for URL capture

Grant these in System Settings → Privacy & Security. After granting, restart the agent.

Apple Silicon (M1/M2/M3) vs Intel: Use the correct installer for your chip architecture. The admin portal will offer the appropriate download based on your device type, but confirm before mass-deploying.

MDM deployment: macOS requires user-approved privacy permissions that cannot be pre-granted through standard MDM profiles for most permission types. On managed devices using an MDM with PPPC (Privacy Preferences Policy Control) capabilities, these permissions can be pre-approved silently. Contact We360 support for the PPPC configuration payload.

Linux

Linux support is for stealth deployments only. Standard (non-stealth) mode is not available.

Known requirements:

  • imagemagick must be installed for screenshot capture

  • D-Bus must be running for power event detection

  • The agent runs under the logged-in user's systemd session

If no data is captured on Linux after installation: Run which import in a terminal. If the command is not found, install imagemagick. Then restart the agent.

Log File Locations

Logs are the primary tool for diagnosing any issue that cannot be resolved from the above sections.

Platform
Standard App
Stealth App

Windows

%APPDATA%\ai.we360\MyZen\logs\

%APPDATA%\ai.zs\zs\logs\

macOS

~/Library/Application Support/MyZenV2/logs/

~/Library/Application Support/ai.zs/zs/logs/

Linux

—

~/.local/share/ai.zs/zs/logs/

Legacy paths (older versions):

  • Windows stealth: %APPDATA%\MyZenV2s\s2\Log\

  • Windows standard: %APPDATA%\MyZenV2\v2\Log\

  • macOS stealth: ~/Library/Application Support/MyZenV2s/Log/

Collecting logs with Desktop Doctor

Desktop Doctor is a diagnostic utility that automatically collects logs, checks network connectivity, and verifies AV status. It is the fastest way to gather everything needed for escalation.

Steps:

  1. Download Desktop Doctor from the Desktop Doctor page and send it to the affected user

  2. Follow the platform-specific launch instructions on that page

  3. Windows: The user double-clicks desktop-doctor.exe

  4. macOS: The user opens Terminal and runs:

  5. Walk through the tabs: Net Check, AV/Firewall Check, DB Check

  6. Go to the Logs/Files Collector tab → check all relevant log files → click Create ZIP

  7. The user emails the ZIP to support, or uploads it using a pre-signed URL provided by support

Manual log collection

If Desktop Doctor is not available:

  1. Press Win+R → type %APPDATA%\ai.zs\zs\logs\ → press Enter

  2. Select all files → right-click → Send to → Compressed folder

  3. Email the ZIP

Escalation Template

When raising an issue with We360 support, include this information to reduce back-and-forth:

Key Rules to Avoid Common Mistakes

Never download the installer from we360.ai/downloads. That page may serve builds that are months old. Always use the admin portal or the links at docs.we360.ai.

Never rename the stealth installer file. The filename encodes tenant identity. Renaming it will cause a silent failure where the agent runs but captures no data and creates no user profile.

Category remapping changes are not applied retroactively. If you have remapped apps or URLs and the new categories are not showing in historical data, contact We360 support — they will need to apply the change to past data on your behalf.

Update the app before deep-diving. A large proportion of reported issues are fixed in newer versions. If the device is on a version that is more than two releases behind the latest, update first.

System clock matters. A clock that is more than a few minutes off from actual time will cause authentication failures, punch-in failures, and data sync errors. Verify system time when something "just doesn't add up."

PreviousDesktop Doctor

Last updated

Was this helpful?