Agent Won't Connect

Your Supervisor agent is installed but doesn't appear in the Fleet Overview. This guide walks you through the most common causes and fixes.

Quick Diagnostic Checklist

Run through these in order — most connection issues are caused by the first three items.

1. Check Network Connectivity

The agent must be able to reach the Management Server on port 4320.

From the Agent Machine

Windows PowerShell:

PS >Test-NetConnection -ComputerName YOUR_SERVER_IP -Port 4320

Linux/macOS:

$nc -zv YOUR_SERVER_IP 4320
# or
$telnet YOUR_SERVER_IP 4320

Expected result: Connection succeeds.

If connection fails:

• Check firewall rules on the server (must allow inbound TCP 4320)
• Verify the server is running (systemctl status collectorctrl-server or Services console)
• Check if a corporate firewall or security group is blocking the port

2. Verify the Endpoint URL

The endpoint in supervisor.yaml must use the correct scheme and path.

Correct Examples

# Unencrypted WebSocket
server:
  endpoint: 'ws://192.168.1.10:4320/v1/opamp'

# TLS WebSocket
server:
  endpoint: 'wss://collectorctrl.company.com:4320/v1/opamp'

Common Mistakes

# ❌ Wrong scheme — uses HTTP instead of WebSocket
endpoint: 'http://192.168.1.10:4320'

# ❌ Missing path — OpAMP path is required
endpoint: 'ws://192.168.1.10:4320'

# ❌ Wrong port — using UI port instead of OpAMP port
endpoint: 'ws://192.168.1.10:4321/v1/opamp'

3. Check the API Token

If your server requires authentication, the Supervisor must present a valid token.

1. In the Admin UI, go to Settings → API Tokens
2. Verify the token you're using is active and not expired
3. Check that the token has the correct role (needs at least viewer)

In supervisor.yaml:

server:
  endpoint: 'wss://your-server:4320/v1/opamp'
  token: 'cct_your_actual_token_here'

Note: The token is only shown once during creation. If you lost it, generate a new one.

4. Check TLS / Certificate Issues

If using wss:// (TLS), certificate validation can fail.

For Testing (Insecure — Not for Production)

server:
  endpoint: 'wss://your-server:4320/v1/opamp'
  tls:
    insecure_skip_verify: true

For Production

Provide the CA certificate that signed your server's TLS certificate:

server:
  endpoint: 'wss://your-server:4320/v1/opamp'
  tls:
    insecure_skip_verify: false
    ca_file: '/etc/collectorctrl/certs/ca.pem'

5. Read the Supervisor Logs

The logs will tell you exactly what's failing.

Windows

PS >Get-Content 'C:\ProgramData\CollectorCtrlSupervisor\supervisor.log' -Tail 50

Linux

$sudo journalctl -u collectorctrl-supervisor -n 50 --no-pager
# or
$sudo tail -n 50 /var/log/collectorctrl/supervisor.log

Common Log Messages

6. Check the Server Logs

If the Supervisor logs look fine, check the server side.

Windows

C:\ProgramData\CollectorCtrl\logs\server.log

Linux

$sudo journalctl -u collectorctrl-server -n 50 --no-pager

Look for:

• Agent connection attempts
• Authentication failures
• TLS handshake errors

7. Verify the Supervisor Service is Running

Windows

PS >Get-Service -Name 'CollectorCtrlSupervisor'
# If stopped:
PS >Start-Service -Name 'CollectorCtrlSupervisor'

Linux

$sudo systemctl status collectorctrl-supervisor
# If inactive:
$sudo systemctl start collectorctrl-supervisor

8. Check for Port Conflicts

Ensure nothing else is using the Supervisor's required ports:

Still Not Working?

If you've checked everything above and the agent still won't connect:

1. Generate a new API token and update supervisor.yaml
2. Restart the Supervisor service to pick up config changes
3. Check server time sync — TLS certificates can fail if clocks are skewed
4. Try with ws:// instead of wss:// to isolate TLS issues
5. Open a GitHub issue with:
   • Supervisor logs (last 50 lines)
   • Server logs (last 50 lines)
   • Your supervisor.yaml (redact the token)
   • Output of Test-NetConnection / nc -zv

Next Steps

• Config changes not applying?
• Read the full troubleshooting docs
• Open an issue on GitHub