Skip to main content

Agent Troubleshooting

Resolve common agent issues and restore security monitoring functionality.

Quick Diagnostic Checklist​

Start here to diagnose most common agent issues:

  1. Check Enrollment - Run castellan-agent status to verify enrollment
  2. Service Status - Verify agent service is running
  3. Network Connectivity - Test connection to CastellanAI servers
  4. Review Logs - Check agent logs for error messages
  5. Verify Permissions - Ensure agent has required system permissions

Agent Showing Disconnected​

Portal displays agent as Disconnected (gray status) but service appears to be running.

Step 1: Verify Service Status​

Windows:

Get-Service "Castellan Agent"
# Should show Status: Running

# If stopped, start it:
Start-Service "Castellan Agent"

Linux:

sudo systemctl status castellan-agent

# If inactive, start it:
sudo systemctl start castellan-agent

macOS:

sudo launchctl list | grep com.castellanai.agent

# If not running, load it:
sudo launchctl load /Library/LaunchDaemons/com.castellanai.agent.plist

Step 2: Check Enrollment Status​

Verify the agent is properly enrolled:

castellan-agent status

You should see:

  • Enrolled: Yes
  • Agent ID, Customer ID, and Worker URL populated

If not enrolled, re-enroll with:

castellan-agent enroll --token YOUR_TOKEN --portal-url https://api.castellanai.com

Step 3: Test Network Connectivity​

Test connection to CastellanAI servers:

Windows:

Test-NetConnection -ComputerName api.castellanai.com -Port 443

Linux/macOS:

curl -v https://api.castellanai.com

Common Issues:

  • Firewall blocking outbound HTTPS (port 443)
  • Proxy configuration required
  • DNS resolution failures

Step 4: Restart Agent Service​

Sometimes a restart resolves temporary communication issues:

Windows:

Restart-Service "Castellan Agent"

Linux:

sudo systemctl restart castellan-agent

macOS:

sudo launchctl unload /Library/LaunchDaemons/com.castellanai.agent.plist
sudo launchctl load /Library/LaunchDaemons/com.castellanai.agent.plist

Step 5: Check Agent Logs​

Review logs for specific error messages:

PlatformLog Location
WindowsC:\ProgramData\CastellanAI\logs\agent.log
Linux/var/log/castellan-agent/agent.log
macOS/Library/Logs/CastellanAI/agent.log

Windows (Event Viewer):

Event Viewer → Applications and Services Logs → CastellanAgent

Linux (journalctl):

sudo journalctl -u castellan-agent -n 100

Agent Stuck in Pending Status​

Agent shows Pending (yellow status) after enrollment.

Troubleshooting Steps​

  1. Verify enrollment completed successfully

    castellan-agent status

  2. Check for enrollment errors in logs

  3. Try re-enrolling with force flag

    castellan-agent enroll --token YOUR_TOKEN --portal-url https://api.castellanai.com --force

  4. Restart the service after re-enrollment

Agent Showing Error Status​

Agent shows Error (red status) in the Portal.

Common Causes​

  • Authentication failures - Invalid or expired credentials
  • Configuration issues - Corrupted configuration file
  • Service crash - Agent service terminated unexpectedly

Solutions​

1. Check enrollment credentials

castellan-agent status

If credentials appear invalid, re-enroll:

castellan-agent enroll --token YOUR_TOKEN --portal-url https://api.castellanai.com --force

2. Run agent in foreground for debugging

castellan-agent run

This shows real-time errors that may not appear in logs.

3. Check configuration file

Verify the configuration file exists and has valid JSON:

PlatformConfig Location
WindowsC:\ProgramData\CastellanAI\appsettings.json
Linux/etc/castellanai/appsettings.json
macOS/Library/Application Support/CastellanAI/appsettings.json

Events Not Appearing in Portal​

Agent shows Connected but events aren't visible in the Portal.

Troubleshooting Steps​

  1. Verify agent is connected - Check status shows Connected (green dot with pulse)

  2. Check Smart Filtering - Low-priority events may be filtered out by Smart Filtering (95-98% data reduction is normal)

  3. Generate test events - Trigger a security event (e.g., failed login) to verify collection

  4. Review agent logs - Look for event collection or transmission errors

  5. Check "Events Today" column - If showing 0 for a Connected agent, there may be a collection issue

  6. Verify permissions - Agent needs permission to read event logs:

    • Windows: Agent service must run as Local System or account with event log access
    • Linux: Agent needs read access to syslog/auth logs
    • macOS: Full Disk Access permission required

Agent Service Won't Start​

Agent service fails to start or crashes immediately.

Troubleshooting Steps​

1. Run manually to see errors

castellan-agent run

2. Check for port conflicts or missing dependencies

3. Verify configuration file syntax

  • Configuration uses JSON format
  • Check for syntax errors (missing commas, brackets)

4. Check system resources

  • Ensure adequate disk space (>100MB free)
  • Verify no resource exhaustion

5. Reinstall if necessary

  • Stop and remove the service
  • Reinstall agent from fresh download
  • Re-enroll with new token

Installation Issues​

Windows Installation​

  • Insufficient Permissions: Run installer as Administrator
  • Previous Installation: Uninstall old version first via Control Panel
  • Antivirus Blocking: Add agent installation path to AV exclusions
  • Service Registration: Ensure sc.exe or PowerShell has admin rights

Linux Installation​

  • Missing Dependencies: Install required packages (libssl, systemd)
  • SELinux/AppArmor: Configure security policies to allow agent
  • Permissions: Ensure install script runs with sudo

macOS Installation​

  • Gatekeeper: Right-click installer → Open to bypass unsigned warning
  • Full Disk Access: Grant in System Preferences → Security & Privacy → Privacy
  • LaunchDaemon Permissions: Ensure plist file has correct ownership

CLI Command Reference​

Use these commands for troubleshooting:

CommandDescription
castellan-agent statusShow enrollment status and agent info
castellan-agent versionShow version, platform, and runtime
castellan-agent runStart agent in foreground (debugging)
castellan-agent enroll --token TOKEN --portal-url URLEnroll with Portal
castellan-agent enroll --token TOKEN --portal-url URL --forceForce re-enrollment
castellan-agent unenrollRemove enrollment (prompts for confirmation)
castellan-agent unenroll --yesRemove enrollment (no prompt)

What's Next?​