Skip to main content

Agent Troubleshooting

Resolve common agent issues and restore security monitoring functionality.

Quick Diagnostic Checklist​

Start Here

Run through this checklist 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​

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

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

Step 2: Check Enrollment Status​

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-NetConnection -ComputerName api.castellanai.com -Port 443

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:

Restart-Service "Castellan Agent"

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
# Check log file
Get-Content "C:\ProgramData\CastellanAI\logs\agent.log" -Tail 50

# Or Event Viewer:
# Event Viewer → Applications and Services Logs → CastellanAgent

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.

Requires Attention

Error status indicates the agent cannot function normally.

Common Causes​

CauseSolution
Authentication failuresRe-enroll with new token
Configuration issuesVerify config file syntax
Service crashCheck logs, restart service

Solutions​

🔐 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
🐛 Run agent in foreground for debugging
castellan-agent run

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

📄 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

Validate JSON syntax:

# Linux/macOS
cat /path/to/appsettings.json | python3 -m json.tool

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 (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:

PlatformPermission Required
WindowsAgent service must run as Local System or account with event log access
LinuxAgent needs read access to syslog/auth logs
macOSFull 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 Issues​

IssueSolution
Insufficient PermissionsRun installer as Administrator
Previous InstallationUninstall old version first via Control Panel
Antivirus BlockingAdd agent installation path to AV exclusions
Service RegistrationEnsure sc.exe or PowerShell has admin rights

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?​

GuideDescription
Agent Health MonitoringMonitor agent status and performance
Agent UpdatesKeep agents up to date
SupportGet help from our support team