The Lucidity agent runs on each managed VM and powers all autoscaling and disk management operations. When the agent goes down, operations on that instance pause until the agent is restored. This article walks you through how to diagnose and recover a down agent.
Before you start
You will need:
- Access to your cloud provider console (AWS EC2, Azure Portal, or GCP Console)
- SSH access to the VM (Linux) or RDP access (Windows)
- Admin or sudo privileges on the VM
Step 1: Confirm the VM is powered on
Check your cloud provider console and verify the VM is in a running state. A powered-off or unreachable VM is the most common reason the agent goes down.
If the VM is stopped, start it from the console and wait a few minutes. The agent should recover automatically once the VM is running.
Step 2: Connect to the VM
- Linux: SSH into the VM
- Windows: RDP into the VM
Step 3: Check agent service status
Lucidity runs two services on each VM: the main agent (autoscalerAgent) and the network agent (nwAgent). Check the status of both.
Linux
sudo systemctl status autoscalerAgent
sudo systemctl status nwAgent
Windows (run in PowerShell or Command Prompt as Administrator)
sc.exe queryex autoscalerAgent
sc.exe queryex nwAgent
If both services show as RUNNING (Windows) or active (running) (Linux), the agent is likely recovering on its own. Wait 2 to 3 minutes and check the dashboard again.
If either service is stopped or in an error state, proceed to Step 4.
Step 4: Restart the agent services
Linux
sudo systemctl restart autoscalerAgent
sudo systemctl restart nwAgent
Windows
Windows services do not have a native restart command. Stop and start each service separately.
sc.exe stop autoscalerAgent
sc.exe start autoscalerAgent
sc.exe stop nwAgent
sc.exe start nwAgent
After restarting, wait 2 to 3 minutes and check the agent status on the Lucidity dashboard. The indicator should clear once the agent reconnects.
Step 5: If the restart fails, reboot the VM
If the service fails to start or the agent remains down after restarting the services, reboot the VM through your cloud provider console or from within the OS.
After the VM comes back up, the agent should start automatically. Allow 3 to 5 minutes for the agent to reconnect and for the dashboard status to update.
Step 6: Contact Lucidity Support
If the agent is still showing as down after a reboot, contact Lucidity support. Include the following in your request:
- Instance name and ID
- Tenant / account name
- Approximate time the agent went down
- Agent logs from the VM
Log locations:
| OS | Log path |
|---|---|
| Linux | /var/log/lucidity/ |
| Windows | C:\ProgramData\lucidity\agent\log |
To view recent Linux agent logs:
sudo journalctl -u autoscalerAgent --since "1 hour ago"
sudo journalctl -u nwAgent --since "1 hour ago"
Common causes
| Symptom | Likely cause |
|---|---|
| Agent down immediately after VM start | VM took longer than expected to boot; agent usually recovers within 5 minutes |
| Agent stuck and service fails to start | Service is in a bad state; reboot the VM |
| Agent repeatedly going down | Resource pressure (CPU/memory) on the VM; review VM sizing |
| Agent down only on Windows | WMI service issue on the VM; check Windows Event Viewer for errors |