Skip to main content

Agent Troubleshooting Guide

Common issues and solutions for Infracast Agent deployments.

Connection Issues​

Agent fails to register​

Symptoms:

  • connection refused or timeout errors during registration
  • Agent never appears in UI

Solutions:

  1. Check network connectivity:

    curl -v https://api.infracast.io/healthz

  2. Verify proxy settings (if applicable):

    export HTTPS_PROXY=http://proxy.example.com:8080
    infracast-agent register --server https://api.infracast.io --token TOKEN

  3. Check enrollment token:

    • Token may be expired (check expiration in UI)
    • Token may have reached max uses
    • Generate a new token and retry

  4. Firewall rules:

    • Ensure outbound HTTPS (443) is allowed
    • Some firewalls require explicit allow for the domain

Agent shows "Offline" immediately after going "Online"​

Cause: Usually a firewall or proxy dropping long-lived connections.

Solutions:

  • Check if corporate proxy has idle connection timeout
  • Verify no DPI (Deep Packet Inspection) is interfering with HTTPS
  • Check for split-horizon DNS issues

Discovery Issues​

No software packages discovered​

Cause: Agent lacks permission to read package databases.

Solutions:

Linux:

# Agent needs read access to:
# /var/lib/dpkg/status (Debian/Ubuntu)
# /var/lib/rpm/rpmdb.sqlite (RHEL/Fedora)

# Check permissions
ls -la /var/lib/dpkg/status
ls -la /var/lib/rpm/

# Agent typically needs to run as root for full discovery

Windows:

# Agent needs read access to HKLM:\SOFTWARE
# Run agent service as LocalSystem or Administrator

No processes discovered​

Cause: Agent can't access process information.

Solutions:

Linux:

# Agent needs access to /proc
# Typically requires root for full process details

# Verify /proc is mounted
mount | grep proc

# Check if running in container without host PID namespace
# Add: hostPID: true in Kubernetes DaemonSet

Windows:

# Agent service needs SeDebugPrivilege for full process info
# Run as LocalSystem

No firewall rules discovered​

Cause: Agent can't execute firewall query commands.

Solutions:

Linux:

# iptables requires root
sudo iptables -L -n

# Or capabilities:
sudo setcap cap_net_admin+ep /usr/local/bin/infracast-agent

macOS:

# pfctl requires root
sudo pfctl -sr

Windows:

# netsh requires Administrator
netsh advfirewall show allprofiles

Service Issues​

Agent service won't start (Linux)​

Check logs:

journalctl -u infracast-agent -n 50 --no-pager

Common causes:

  1. Missing config file:

    ls -la /etc/infracast-agent/config.json
    # If missing, re-run registration

  2. Permission denied:

    # Ensure binary is executable
    chmod +x /usr/local/bin/infracast-agent

  3. SELinux blocking:

    ausearch -m avc -ts recent | grep infracast
    # If blocked, create policy or run in permissive

Agent service won't start (Windows)​

Check Event Viewer:

  1. Open Event Viewer
  2. Navigate to Windows Logs → Application
  3. Filter by Source: InfracastAgent

Common causes:

  1. Missing dependencies:

    • Install Visual C++ Redistributable if needed

  2. Service account permissions:

    • Ensure service account has "Log on as a service" right

Agent service won't start (macOS)​

Check logs:

log show --predicate 'subsystem == "io.infracast.agent"' --last 1h

Common causes:

  1. Gatekeeper blocking:

    # Remove quarantine attribute
    xattr -d com.apple.quarantine /usr/local/bin/infracast-agent

  2. TCC (Transparency, Consent, and Control):

    • Grant Full Disk Access in System Preferences → Privacy & Security

Performance Issues​

High CPU usage​

Cause: Collectors running too frequently or hanging.

Solutions:

  1. Increase scan interval: Edit /etc/infracast-agent/config.json:

    {
      "scan_interval_seconds": 600
    }

  2. Check for runaway process discovery:

    • On systems with thousands of processes, discovery is expensive
    • Consider filtering process discovery

High memory usage​

Cause: Large discovery reports accumulating.

Solutions:

  1. Check report size:

    • Systems with many packages/processes generate large reports
    • Default report retention is minimal (current + previous)

  2. Restart agent:

    sudo systemctl restart infracast-agent

Token and Authentication Issues​

"Token revoked" error​

Cause: Agent token was revoked from the UI.

Solution:

  1. Generate new enrollment token in UI
  2. Re-register agent: 
    sudo infracast-agent register --server URL --token NEW_TOKEN --force

"Token expired" error​

Cause: JWT token has exceeded its validity period.

Solution:

  • Agent should automatically refresh token on heartbeat
  • If persistent, re-register with new enrollment token

"Tenant mismatch" error​

Cause: Agent registered to different tenant than current token.

Solution:

  1. Revoke agent in original tenant
  2. Re-register with correct tenant's enrollment token: 
    sudo infracast-agent register --server URL --token TOKEN --force

Kubernetes-Specific Issues​

Agent pods in CrashLoopBackOff​

Check logs:

kubectl logs -n infracast -l app=infracast-agent --tail=100

Common causes:

  1. Missing enrollment token secret:

    kubectl get secret -n infracast infracast-agent-token
    # If missing, create it:
    kubectl create secret generic infracast-agent-token \
      --from-literal=token=YOUR_TOKEN -n infracast

  2. Insufficient permissions:

    • DaemonSet needs hostPID: true and hostNetwork: true
    • SecurityContext may need privileged: true

Agents all showing same hostname​

Cause: Using pod hostname instead of node hostname.

Solution: Add to DaemonSet spec:

env:
- name: HOSTNAME
  valueFrom:
    fieldRef:
      fieldPath: spec.nodeName

Getting Help​

If issues persist:

  1. Collect diagnostics:

    infracast-agent diagnostics > /tmp/agent-diag.txt

  2. Include:

    • Agent version: infracast-agent version
    • OS version: uname -a or systeminfo
    • Relevant log excerpts
    • Network trace if connectivity issue

  3. Contact support or file GitHub issue with diagnostics attached.