---
title: "Agent Troubleshooting"
slug: "agent-troubleshooting"
updated: 2026-05-19T12:21:07Z
published: 2026-05-19T12:21:07Z
---

> ## 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.

# Agent Troubleshooting

Use the guidance below to diagnose and resolve common agent issues.

---

## Agent Status: Offline

If an agent appears **Offline**, it is not currently communicating with the Verax 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. **Check network connectivity to the Verax server.**

**Windows (PowerShell):**

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

**macOS / Linux:**

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

If the connection fails, review firewall rules and routing configuration.
3. **Ensure the agent service is running.**

Restart if necessary:

```plaintext
sudo systemctl restart verax-agent
```
  - Windows: Check the `verax-agent` service in Services.
  - macOS / Linux:

```plaintext
sudo systemctl status verax-agent
```
4. **Reinstall the agent if needed** using a valid installation token.

---

## Agent Status: Online but Health: Unhealthy

If an agent is **Online but Unhealthy**, it is connected to the Verax server but not fully operational.

### Common Causes

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

### Troubleshooting Steps

1. **Verify the Verax CA certificate is installed and trusted.**
2. **Confirm hosts file entries are present and correct.**
3. **Flush DNS cache after making changes.**

Windows:

```plaintext
ipconfig /flushdns
```

macOS:

```plaintext
sudo dscacheutil -flushcache
sudo killall -HUP mDNSResponder
```
4. **Verify required environment variables (if applicable).**
5. **Restart the**`verax-agent`**service after correcting configuration.**

---

## Agent Is Online and Healthy but No Activity Is Recorded

If an agent shows as Online and Healthy but no activity appears:

- Confirm the endpoint is actively using supported AI tools
- Verify traffic redirection is correctly configured
- Ensure the correct Verax server address was used during installation

---

If issues persist after completing these steps, contact Verax Support and provide:

- Operating system
- Agent version
- Verax server address
- Description of the observed behavior

---

Clean, focused, and strictly troubleshooting-only.