Troubleshooting Guide

Common issues and solutions for PumaGate gateway, agent, and access problems.

Diagnostic Decision Tree

Follow this flowchart to quickly identify and resolve common issues.

Issue Detected Is the agent running? See: Not Starting NO Server visible in UI? YES See: No Data NO Sessions connecting OK? YES See: Sessions NO Performance acceptable? YES See: Performance NO All Systems Healthy YES Quick Diagnostic Commands Check agent status systemctl status pumagate-agent View recent logs journalctl -u pumagate-agent -n 50 Test connectivity curl -v https://server/api/v1/health Check kernel version uname -r Follow logs live journalctl -u pumagate-agent -f

Agent Not Starting

Symptom: Logs show "permission denied" or "operation not permitted"

Cause: The agent requires root privileges or specific capabilities

# Ensure service runs as root
grep -E "^User=" /etc/systemd/system/pumagate-agent.service

# For non-root with capabilities:
sudo setcap cap_bpf,cap_perfmon,cap_net_admin+ep /opt/pumagate/bin/pumagate-agent

Symptom: "No such file or directory" or "executable not found"

# Check if binary exists and is executable
ls -la /opt/pumagate/bin/pumagate-agent
file /opt/pumagate/bin/pumagate-agent

# Re-download if needed
curl -LO https://updates.pumagate.com/pumagate-agent-linux-amd64
chmod +x pumagate-agent-linux-amd64
sudo mv pumagate-agent-linux-amd64 /opt/pumagate/bin/pumagate-agent

Symptom: Agent exits immediately with configuration errors

# Check configuration file
cat /opt/pumagate/etc/agent.env

# Verify required variables are set
grep AGENT_API_URL /opt/pumagate/etc/agent.env
grep AGENT_TENANT_ID /opt/pumagate/etc/agent.env

# Test with explicit flags
/opt/pumagate/bin/pumagate-agent \
  --server=https://pumagate.example.com \
  --tenant-id=00000000-0000-0000-0000-000000000000

No Data in Dashboard

Symptom: Agent running but server appears in wrong organisation or not at all

# Check configured tenant ID
grep AGENT_TENANT_ID /opt/pumagate/etc/agent.env

# Verify in logs
journalctl -u pumagate-agent | grep "TenantID"

# Update if incorrect
sudo sed -i 's/AGENT_TENANT_ID=.*/AGENT_TENANT_ID=correct-uuid-here/' \
  /opt/pumagate/etc/agent.env
sudo systemctl restart pumagate-agent

Symptom: Logs show "Export failed" or "Failed to send request"

# Check for export errors
journalctl -u pumagate-agent | grep -i export

# Verify server is reachable
curl -v https://pumagate.com/api/v1/health

# Check if data is being queued to disk
ls -la /opt/pumagate/data/queue/

Symptom: Data appears at wrong times or authentication validation fails

# Check system time
date

# Sync with NTP
sudo timedatectl set-ntp true

# Or manually sync
sudo ntpdate pool.ntp.org

Connectivity Issues

Agent DNS Resolve hostname Firewall Port 443 open? TLS/Proxy Cert valid? pumagate.com Healthy? nslookup / dig nc -zv :443 openssl s_client curl /health

Symptom: Connection timeout or refused

# Test connectivity to PumaGate platform
curl -v --connect-timeout 10 https://pumagate.com/api/v1/health

# Check iptables rules
sudo iptables -L -n | grep -E "(DROP|REJECT)"

# Verify port 443 is reachable
nc -zv pumagate.com 443

Symptom: "certificate verify failed" or TLS handshake errors

# Check certificate for PumaGate platform
openssl s_client -connect pumagate.com:443 -servername pumagate.com

# Update CA certificates on the host
sudo update-ca-certificates

Symptom: Connection fails in environments requiring a proxy

# Set proxy environment variables
export HTTPS_PROXY=http://proxy.example.com:8080
export HTTP_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1

# Or add to systemd service override
sudo systemctl edit pumagate-agent
# Add under [Service]:
# Environment="HTTPS_PROXY=http://proxy.example.com:8080"

Session Issues

Symptom: SSH session times out or shows "connection refused"

  • Verify the Agent is running and connected to the Gateway (WebSocket)
  • Check the agent's embedded SSH server is listening: ss -tlnp | grep 2222
  • Check that the stored credentials are valid and the agent can resolve them locally
  • Review Gateway logs for session routing errors
# Check agent SSH port
ss -tlnp | grep 2222

# Check agent connectivity
journalctl -u pumagate-agent | grep -i websocket

# Verify the agent is registered and connected
journalctl -u pumagate-agent | grep -i "registered\|connected"

Symptom: Sessions connect but no recordings appear in the dashboard

  • Verify the agent is connected and registered in the PumaGate dashboard
  • Check agent logs for any connection errors during the session
  • Ensure outbound HTTPS (port 443) to pumagate.com and *.pumagate.com is allowed
  • Contact support@pumagate.com if recordings are still missing after verification
# Check agent logs during the session time window
journalctl -u pumagate-agent --since "1 hour ago" | grep -i "error\|session"

Performance Issues

The agent typically uses less than 1% CPU and under 50 MB RAM. If you observe higher usage:

1. High Connection Volume

Servers with thousands of connections per second may see higher CPU.

# Check connection rate
ss -s
3. Log Flooding
# Check log volume
journalctl -u pumagate-agent --since "1 hour ago" | wc -l

# Reduce log level if too verbose
AGENT_LOG_LEVEL=warn
4. Session Latency

If sessions feel slow, verify network connectivity between the agent and the PumaGate platform.

# Test latency to PumaGate platform
curl -o /dev/null -s -w "Connect: %{time_connect}s\nTotal: %{time_total}s\n" \
  https://pumagate.com/api/v1/health

Getting Help

Documentation

Review all documentation pages for detailed guidance

View Docs
Downloads

Download the latest agent binaries and updates

Get Agent
Email Support

Contact our support team for direct assistance

Contact Support
When contacting support, please include:
  • Agent version (pumagate-agent --version)
  • Operating system and kernel version (uname -a)
  • Relevant log output (journalctl -u pumagate-agent -n 100)
  • Configuration file (with sensitive values redacted)