---
title: "Troubleshooting Endpoint Agents"
slug: "agent-troubleshooting"
updated: 2026-09-07T08:30:31Z
published: 2026-09-07T08:30:31Z
canonical: "docs.verax.ai/agent-troubleshooting"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verax.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Endpoint Agents

Use this guide to diagnose and resolve common Endpoint Agent issues.

---

## Agent Status: Offline

If an Endpoint Agent appears **Offline**, it is not currently communicating with the Verax Protect server.

## Common Causes

- The endpoint is powered off.
- Network connectivity issues.
- Required ports (TCP 3000 and TCP 3002) are blocked.
- The `verax-agent` service is not running.

## Troubleshooting Steps

### 1. Verify the endpoint is powered on.

### 2. Verify connectivity to the Verax Protect server.

**Windows (PowerShell)**

```powershell
Test-NetConnection <VERAX_SERVER> -Port 3000
Test-NetConnection <VERAX_SERVER> -Port 3002
```

**macOS / Linux**

```bash
nc -zv <VERAX_SERVER> 3000
nc -zv <VERAX_SERVER> 3002
```

If the connection fails, review your firewall rules and network routing.

### 3. Verify the Endpoint Agent service is running.

**Windows**

Open **Services** and verify that the **verax-agent** service is running.

**macOS / Linux**

```bash
sudo systemctl status verax-agent
```

Restart the service if necessary:

```bash
sudo systemctl restart verax-agent
```

### 4. Reinstall the Endpoint Agent if necessary.

Reinstall the agent using a valid installation token.

---

## Agent Status: Online, Health: Unhealthy

If an Endpoint Agent is **Online** but **Unhealthy**, it is communicating with the Verax Protect server but one or more required components are not functioning correctly.

The troubleshooting steps depend on the deployment mode.

---

## Configuration Mode

### Common Causes

- Verax CA certificate is not installed or not trusted.
- Hosts file is not configured correctly.
- DNS cache was not flushed after configuration changes.
- Required environment variables are missing.

### Troubleshooting Steps

1. Verify the Verax CA certificate is installed and trusted.
2. Verify the hosts file contains the expected entries.
3. Flush the DNS cache.

**Windows**

```cmd
ipconfig /flushdns
```

**macOS**

```bash
sudo dscacheutil -flushcache
sudo killall -HUP mDNSResponder
```

1. Verify any required environment variables.
2. Restart the Endpoint Agent service.

---

## Full Mode

### Common Causes

- Verax CA certificate is not installed or not trusted.
- The local proxy is not running.
- Required environment variables are missing.
- Local traffic interception is not functioning correctly.

### Troubleshooting Steps

1. Verify the Verax CA certificate is installed and trusted.
2. Verify the Endpoint Agent service is running.
3. Verify the local proxy is listening.
4. Verify any required environment variables.
5. Restart the Endpoint Agent service.

---

## Agent Status: Online, Health: Healthy, but No Activity Is Recorded

If an Endpoint Agent is **Online** and **Healthy**, but no activity appears in Verax Protect:

### Verify that:

- The endpoint is actively using supported AI tools.
- The Endpoint Agent was installed in the expected deployment mode.
- The Verax Protect server address configured during installation is correct.

For **Configuration** mode:

- Verify that endpoint configuration (such as hosts file entries) is present and correct.

For **Full** mode:

- Verify that local traffic interception is functioning correctly.

If the issue persists, contact Verax Support and provide:

- Operating system
- Endpoint Agent version
- Deployment mode (Configuration or Full)
- Verax Protect server address
- Description of the observed behavior