Agent Troubleshooting

This guide covers common agent issues and their solutions. The current public agent support focus is Windows and Linux; macOS troubleshooting applies to Preview/Experimental lab builds only.

Agent Not Connecting

Symptoms

Agent shows as offline in console
No telemetry data received from endpoint
Agent logs show connection errors

Diagnostic Steps

Check agent status

   tamandua-agent --status

Test server connectivity

   tamandua-agent --test-connection

Check agent logs

   # Windows
   type C:\ProgramData\Tamandua\logs\tamandua-agent.log

   # Linux
   tail -100 /var/log/tamandua/tamandua-agent.log

   # macOS Preview
   tail -100 "/Library/Application Support/Tamandua/logs/agent.log"

Common Causes and Solutions

Connection Refused

Error:

ERROR tamandua_agent::transport: Connection refused (os error 111)
ERROR tamandua_agent::transport: Failed to connect to wss://server:4000/socket/agent

Solution:

Verify the server is running:

   curl -k https://your-server:4000/api/health

Check the server URL in agent configuration
Verify firewall allows outbound connections on port 4000

DNS Resolution Failed

Error:

ERROR tamandua_agent::transport: Failed to resolve hostname: server.example.com

Solution:

Verify DNS resolution:

   nslookup server.example.com

Check /etc/resolv.conf (Linux) or DNS settings (Windows)
Try using IP address directly in configuration

TLS Handshake Failed

Error:

ERROR tamandua_agent::transport: TLS handshake failed: certificate verify failed
ERROR tamandua_agent::transport: HandshakeError: certificate has expired

Solution:

Verify certificate validity:

   openssl s_client -connect server:4000 -showcerts 2>/dev/null | openssl x509 -noout -dates

Install updated CA certificates on the endpoint
Check system time is synchronized

WebSocket Upgrade Failed

Error:

ERROR tamandua_agent::transport: WebSocket upgrade failed: HTTP 401 Unauthorized
ERROR tamandua_agent::transport: Authentication failed: invalid token

Solution:

Regenerate agent token from console
Update token in agent configuration:

   # Windows
   notepad C:\ProgramData\Tamandua\config.toml

   # Linux
   sudo nano /etc/tamandua/config.toml

   # macOS Preview
   sudo nano "/Library/Application Support/Tamandua/config/agent.toml"

Restart agent service

Connection Timeout

Error:

ERROR tamandua_agent::transport: Connection timeout after 30s

Solution:

Check network connectivity:

   ping server.example.com
   telnet server.example.com 4000

Verify proxy configuration if applicable
Check for firewall blocking WebSocket connections

High CPU Usage

Symptoms

Agent process consuming excessive CPU
System performance degradation
User complaints about slow endpoints

Diagnostic Steps

Check CPU usage

   # Windows
   tasklist /FI "IMAGENAME eq tamandua-agent.exe" /FO LIST

   # Linux
   top -p $(pgrep tamandua-agent)

   # macOS Preview
   top -pid $(pgrep tamandua-agent)

Enable debug logging to identify activity

   RUST_LOG=debug tamandua-agent --server wss://...

Common Causes and Solutions

Aggressive Collection Settings

Solution:

Adjust collection intervals in config.toml:

[collectors]
process_interval_ms = 5000     # Increase from default 1000
file_interval_ms = 10000       # Increase from default 2000
network_interval_ms = 5000     # Increase from default 1000

Large Process Table

Solution:

Configure process filtering:

[collectors.process]
exclude_patterns = [
    "System Idle Process",
    "chrome.exe",    # High-volume processes
    "node.exe"
]
max_processes = 1000

Recursive File Monitoring

Error: Agent monitoring large directories with deep recursion. Solution:

Limit file monitoring scope:

[collectors.file]
watch_paths = [
    "/tmp",
    "/var/tmp",
    "/home/*/Downloads"
]
exclude_paths = [
    "/var/log/journal",    # Exclude high-churn directories
    "*.log"
]
max_depth = 3

YARA Scan Overload

Solution:

Tune YARA scanning parameters:

[analyzers.yara]
enabled = true
scan_on_create = true
scan_on_modify = false    # Reduce scan frequency
max_file_size_mb = 50     # Skip large files
concurrent_scans = 2      # Limit parallel scans

Entropy Calculation on Large Files

Solution:

Limit entropy analysis:

[analyzers.entropy]
enabled = true
max_file_size_mb = 10
sample_size_bytes = 65536

Certificate Errors

Symptoms

Agent cannot establish secure connection
TLS/SSL handshake failures
Certificate validation errors

Diagnostic Steps

Check certificate

   openssl s_client -connect server:4000 -showcerts

Verify certificate chain

   openssl verify -CAfile ca.pem server.pem

Common Causes and Solutions

Certificate Expired

Error:

ERROR tamandua_agent::transport: Certificate has expired

Solution:

Renew server certificate
Deploy updated certificate to server
Restart server and reconnect agents

Self-Signed Certificate Not Trusted

Error:

ERROR tamandua_agent::transport: Certificate verification failed: self-signed certificate

Solution (Development):

# config.toml - NOT for production
[transport]
tls_verify = false

Solution (Production):

Install CA certificate on endpoint:

   # Linux
   sudo cp tamandua-ca.pem /usr/local/share/ca-certificates/tamandua-ca.crt
   sudo update-ca-certificates

   # Windows
   certutil -addstore -f "ROOT" tamandua-ca.pem

Or specify CA in configuration:

   [transport]
   ca_cert_path = "/etc/tamandua/ca.pem"

Certificate CN Mismatch

Error:

ERROR tamandua_agent::transport: Certificate CN 'wrong-host' does not match 'server.example.com'

Solution:

Regenerate certificate with correct CN/SAN
Or update server URL to match certificate

mTLS Client Certificate Issues

Error:

ERROR tamandua_agent::transport: Client certificate required
ERROR tamandua_agent::transport: Client certificate rejected

Solution:

Verify client certificate path:

   [transport]
   client_cert_path = "/etc/tamandua/agent.pem"
   client_key_path = "/etc/tamandua/agent-key.pem"

Check certificate validity and chain
Verify certificate was signed by trusted CA

Enrollment Failures

Symptoms

New agent cannot register with server
Enrollment token rejected
Agent stuck in "pending" state

Diagnostic Steps

Check enrollment token in the admin console

Confirm its expiry, revocation and remaining-use state. The agent has no

standalone token-validation command; retry enrollment only through

tamandua-agent install and its hidden prompt.

Review server enrollment logs

   grep "enrollment" /var/log/tamandua-server/app.log

Common Causes and Solutions

Token Expired

Error:

ERROR tamandua_agent::enrollment: Enrollment token expired

Solution:

Generate new enrollment token from console
Re-run enrollment:

   tamandua-agent install

Paste the new enrollment token into the hidden prompt. For automation, use

install --token-stdin and deliver it directly on standard input.

Token Already Used

Error:

ERROR tamandua_agent::enrollment: Enrollment token already used (single-use tokens)

Solution:

Generate new enrollment token with appropriate usage limits
For bulk deployments, use multi-use tokens with organization scope

License Limit Reached

Error:

ERROR tamandua_agent::enrollment: Enrollment rejected: license limit exceeded

Solution:

Check license status in console (Settings > License)
Remove inactive/stale agents
Upgrade license for more endpoints

Organization Not Found

Error:

ERROR tamandua_agent::enrollment: Organization ID not found: org-12345

Solution:

Verify organization ID in enrollment token
Check organization exists and is active in console

Network Policy Blocking Enrollment

Error:

ERROR tamandua_agent::enrollment: Connection timeout during enrollment

Solution:

Verify endpoint can reach enrollment endpoint
Check firewall allows HTTPS to server
Verify proxy configuration

Agent Crashes

Symptoms

Agent process terminates unexpectedly
Service restarts frequently
Crash dumps generated

Diagnostic Steps

Check crash logs

   # Windows
   type C:\ProgramData\Tamandua\crash_dumps\*.log

   # Linux
   journalctl -u tamandua-agent --since "1 hour ago"
   coredumpctl list tamandua-agent

Check system logs

   # Windows Event Log
   Get-EventLog -LogName Application -Source "Tamandua Agent" -Newest 20

   # Linux
   dmesg | grep -i tamandua

Common Causes and Solutions

Out of Memory

Error:

ERROR tamandua_agent: Out of memory
thread 'main' panicked at 'memory allocation failed'

Solution:

Check system memory:

   free -m   # Linux

Increase agent memory limits or reduce collection scope
Check for memory leaks in recent versions

Stack Overflow

Error:

thread 'collector-process' has overflowed its stack

Solution:

Update to latest agent version
Check for deep recursion in file monitoring
Increase stack size:

   RUST_MIN_STACK=8388608 tamandua-agent ...

Panic in Collector

Error:

thread 'collector-network' panicked at 'assertion failed: socket.is_valid()'

Solution:

Disable problematic collector temporarily:

   [collectors.network]
   enabled = false

Report issue with stack trace to support
Update to patched version when available

Permission Denied

Error:

ERROR tamandua_agent::collectors::process: Access denied: cannot enumerate processes
thread 'main' panicked at 'Required permissions not available'

Solution:

Run agent with elevated privileges:

   # Linux
   sudo systemctl restart tamandua-agent

   # Windows - Run as Administrator

Check required permissions are granted
Verify SELinux/AppArmor policies (Linux)

Collection Gaps

Symptoms

Missing telemetry data for time periods
Incomplete process/file/network events
Detection rules not triggering

Diagnostic Steps

Check collection status

   tamandua-agent --list-collectors

Review collector logs

   grep "collector" /var/log/tamandua/tamandua-agent.log

Common Causes and Solutions

Collector Disabled

Solution:

Enable required collectors:

[collectors]
process = true
file = true
network = true
dns = true
registry = true    # Windows only

Buffer Overflow

Error:

WARN tamandua_agent::transport: Event buffer full, dropping events

Solution:

Increase buffer size:

[transport]
buffer_size = 10000      # Increase from default 1000
batch_size = 100         # Adjust batch size
flush_interval_ms = 1000 # More frequent flushing

Network Disconnection

Error:

WARN tamandua_agent::transport: Disconnected, buffering events
WARN tamandua_agent::transport: Reconnection attempt 3/10

Solution:

Events are buffered during disconnection (up to buffer limit)
Increase buffer for resilience:

   [transport]
   offline_buffer_size = 50000
   offline_buffer_persist = true

Investigate network stability

Collector Errors

Error:

ERROR tamandua_agent::collectors::file: Failed to read directory: /proc
ERROR tamandua_agent::collectors::process: WMI query failed: RPC server unavailable

Solution:

Check collector-specific permissions
Verify system dependencies (WMI service on Windows)
Check for filesystem issues

Rate Limiting

Error:

WARN tamandua_agent::transport: Rate limited by server, backing off

Solution:

Adjust collection intervals to reduce event volume
Configure server-side rate limits appropriately
Use filtering to reduce noise:

   [collectors.process]
   exclude_users = ["SYSTEM", "LOCAL SERVICE"]
   exclude_patterns = ["chrome.exe", "firefox.exe"]

Platform-Specific Issues

Windows-Specific

WMI Service Not Running

Error:

ERROR tamandua_agent::collectors::process: WMI service unavailable

Solution:

Start-Service Winmgmt
Set-Service Winmgmt -StartupType Automatic

Windows Defender Interference

Error:

WARN tamandua_agent: File access blocked by antivirus

Solution:

Add exclusions for Tamandua:

Add-MpPreference -ExclusionPath "C:\Program Files\Tamandua"
Add-MpPreference -ExclusionProcess "tamandua-agent.exe"

Linux-Specific

Auditd Conflicts

Error:

ERROR tamandua_agent::collectors::audit: Auditd conflict: rules already exist

Solution:

Review existing audit rules:

   auditctl -l

Merge rules or disable conflicting auditing

SELinux Blocking

Error:

ERROR tamandua_agent: Permission denied (SELinux)

Solution:

# Check SELinux denials
ausearch -m AVC -ts recent

# Create policy module
audit2allow -a -M tamandua
semodule -i tamandua.pp

macOS Preview/Experimental

System Extension Approval

Error:

ERROR tamandua_agent: System extension not approved

Solution:

Open System Preferences > Security & Privacy
Click "Allow" for Tamandua extension
Restart agent

Full Disk Access Required

Error:

ERROR tamandua_agent::collectors::file: Permission denied: /Users/*/Library

Solution:

Open System Preferences > Security & Privacy > Privacy
Select "Full Disk Access"
Add Tamandua Agent

macOS behavior may vary by preview build, OS version, MDM profile, and installed Endpoint Security clients. Validate fixes on a controlled test host before using them in a broader fleet.

Next Steps

Server Troubleshooting - Backend server issues
Network Troubleshooting - Connectivity problems
Detection Troubleshooting - Detection rule issues
Troubleshooting Overview - General diagnostic tools