Connectivity Issues

Diagnose and resolve agent communication problems, network connectivity issues, and firewall configuration errors.

Systematic Approach

Follow the diagnostic steps in order to quickly identify and resolve connectivity problems.

---

Common Symptoms

Symptom	Description
Agent Offline	Agent cannot establish connection to CastellanAI backend
Intermittent Drops	Agent alternates between online and offline status
Events Not Appearing	Agent connected but events not transmitted
High Latency	Events take longer than 30 seconds to appear

---

Diagnostic Steps

1️⃣ Service Status

Step 1: Check Agent Service Status

Verify the CastellanAI agent service is running.

Windows:

Get-Service CastellanAgent | Select-Object Status, StartType

Linux:

sudo systemctl status castellan-agent

Status	Action
Running	Proceed to Step 2
Stopped	Start the service
Not Found	Reinstall agent

2️⃣ Network Test

Step 2: Test Network Connectivity

Verify the agent can reach CastellanAI backend endpoints.

Test HTTPS connectivity:

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

Test WebSocket connectivity:

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

Result	Meaning
TcpTestSucceeded: True	Connection successful
TcpTestSucceeded: False	Firewall or network blocking

3️⃣ Review Logs

Step 3: Review Agent Logs

Check agent logs for connection errors or authentication failures.

Platform	Log Location
Windows	C:\ProgramData\CastellanAgent\logs\agent.log
Linux	/var/log/castellan-agent/agent.log

Look for these error patterns:

Error	Meaning
Connection timeout	Network or firewall issue
Certificate validation	SSL/TLS configuration problem
Token expired/invalid	Re-authentication needed
DNS lookup failed	DNS resolution issue

4️⃣ Firewall Rules

Step 4: Verify Firewall Rules

Ensure firewall allows outbound HTTPS and WebSocket connections.

Required outbound rules:

Destination	Protocol	Port
api.castellanai.com	HTTPS	443
ws.castellanai.com	WebSocket (WSS)	443
updates.castellanai.com	HTTPS	443

5️⃣ Proxy Config

Step 5: Check Proxy Configuration

If your organization uses a proxy, verify agent proxy settings.

Configure proxy in agent.yaml:

proxy:
  enabled: true
  server: proxy.company.com
  port: 8080
  authentication:
    username: proxy-user
    password: proxy-password
  bypass:
    - localhost
    - 127.0.0.1

---

Common Issues and Solutions

🔐 SSL Errors

SSL Certificate Validation Failures

Symptom: Logs show "SSL certificate validation failed"

Solution	Description
Check Date/Time	Ensure system clock is accurate
Update Certificates	Install latest root certificates
Corporate CA	Import corporate CA certificate if using SSL inspection
Update Agent	Latest version has updated certificate bundle

🔑 Auth Errors

Authentication Token Expired

Symptom: "401 Unauthorized" errors in logs

Solution:

1. Navigate to Agents page in dashboard
2. Find affected agent and click Regenerate Token
3. Copy new token to agent configuration file
4. Restart agent: Restart-Service CastellanAgent

🔄 Intermittent

Intermittent Connection Drops

Symptom: Agent frequently disconnects and reconnects

Solution	Configuration
Check Network Stability	Test for packet loss/latency
Adjust Keep-Alive	keepalive_interval: 30
Increase Timeout	connection_timeout: 60
Check Firewall	Long-lived connection timeouts

🌐 DNS Errors

DNS Resolution Failures

Symptom: "Unable to resolve hostname" errors

Solution	Command/Action
Test DNS	nslookup api.castellanai.com
Verify DNS Servers	Check they're reachable
Add Hosts Entry	Fallback in hosts file
Custom DNS	Configure in agent settings

---

Automated Connectivity Test

CastellanAI provides a built-in connectivity test tool.

Run the test:

castellan-agent test-connection

Expected output for healthy connection:

Connectivity Test Results:
✓ DNS Resolution: api.castellanai.com → 52.168.10.5
✓ HTTPS Connection: Port 443 (200 OK)
✓ WebSocket Connection: Port 443 (Connected)
✓ Authentication: Token valid
✓ Event Transmission: Test event sent successfully

Status: All checks passed

Failed Checks

If any checks fail, the tool provides specific error messages and resolution suggestions.

---

Prevention Best Practices

Practice	Description
Monitor Agent Health	Enable notifications for offline agents
Document Network Requirements	Provide firewall teams with complete requirements
Keep Agents Updated	Enable automatic updates for connectivity fixes
Test After Changes	Run connectivity tests after network maintenance

📝 Connectivity Troubleshooting Checklist

• Verify agent service is running
• Test network connectivity to CastellanAI endpoints
• Review agent logs for specific errors
• Check firewall rules allow required ports
• Verify proxy configuration if applicable
• Run automated connectivity test
• Contact support if issue persists

---

What's Next?

Guide	Description
Agent Health Monitoring	Monitor agent status and configure alerts
Agent Troubleshooting	Comprehensive agent troubleshooting guide
Performance Optimization	Optimize agent performance