Skip to main content

Common Issues

Solutions to the most frequently encountered PatchCTL issues.

Server Not Appearing​

Symptom: Agent installed but server not visible in dashboard.

Causes and Solutions:

1. Agent Not Running​

# Check status
sudo systemctl status patchctl

# If not running, start it
sudo systemctl start patchctl

2. License Key Invalid​

# Verify license key
sudo cat /etc/patchctl/config.json | grep license_key

# Compare with dashboard: Settings → Account → License Key

3. Network Blocked​

# Test API connectivity
curl -I https://api.patchctl.com/health

# Expected: HTTP/2 200

4. DNS Issues​

# Test DNS resolution
nslookup api.patchctl.com

# If fails, check /etc/resolv.conf

5. Wait for Heartbeat​

First heartbeat can take up to 5 minutes. Check logs:

sudo journalctl -u patchctl | grep -i heartbeat

Agent Offline​

Symptom: Server shows "Offline" in dashboard.

Causes and Solutions:

1. Service Stopped​

sudo systemctl restart patchctl

2. Network Connectivity Lost​

# Test from server
curl -I https://api.patchctl.com/health

3. Server Rebooted​

Agent should start automatically. If not:

sudo systemctl enable patchctl
sudo systemctl start patchctl

4. Agent Crashed​

Check for errors:

sudo journalctl -u patchctl --since "1 hour ago"

Patches Failing​

Symptom: Patch operations fail or timeout.

Causes and Solutions:

1. Package Manager Locked​

# Ubuntu/Debian
sudo rm /var/lib/dpkg/lock-frontend
sudo rm /var/lib/apt/lists/lock

# RHEL/Rocky
sudo rm /var/run/dnf.pid

# SUSE
sudo rm /var/run/zypp.pid

2. Disk Full​

# Check disk space
df -h /

# Clean up if needed
sudo apt clean        # Debian/Ubuntu
sudo dnf clean all    # RHEL/Rocky
sudo zypper clean     # SUSE

3. Broken Dependencies​

# Ubuntu/Debian
sudo apt --fix-broken install
sudo dpkg --configure -a

# RHEL/Rocky
sudo dnf distro-sync

# SUSE
sudo zypper verify

4. Repository Errors​

# Refresh repositories
sudo apt update           # Debian/Ubuntu
sudo dnf makecache        # RHEL/Rocky
sudo zypper refresh       # SUSE

CVE Data Missing​

Symptom: No CVE data showing for servers.

Causes and Solutions:

1. Initial Sync Pending​

CVE correlation happens after:

  • Agent registers (immediate)
  • Package scan completes (up to 6 hours)
  • CVE data synced (daily)

Wait 24 hours for new servers.

2. Force Package Scan​

Trigger immediate scan:

  1. Go to server details
  2. Click Actions → Refresh

3. Unsupported Packages​

Some packages may not have CVE data:

  • Custom/internal packages
  • Third-party repositories
  • Very new packages

Schedules Not Running​

Symptom: Schedule exists but doesn't execute.

Causes and Solutions:

1. Schedule Disabled​

Check schedule is enabled in the Schedules page.

2. No Matching Targets​

Verify target criteria matches servers:

  • Environment tags
  • Custom tags
  • OS filter
  • Hostname pattern

3. Timezone Mismatch​

Confirm schedule timezone matches expectations.

4. All Servers Offline​

Schedule skips offline servers. Ensure targets are online.

Dashboard Performance​

Symptom: Dashboard loading slowly.

Causes and Solutions:

1. Many Servers​

Large fleets may load slower. Use filters to reduce displayed servers.

2. Browser Cache​

Clear browser cache or try incognito mode.

3. Network Latency​

Check your connection to app.patchctl.com.

Login Issues​

Symptom: Can't log into dashboard.

Causes and Solutions:

1. Wrong Credentials​

Use Forgot Password to reset.

2. Account Locked​

After multiple failed attempts, wait 15 minutes.

3. Browser Issues​

  • Clear cookies
  • Try different browser
  • Disable extensions

4. Organization Deleted​

Contact support if organization was deleted.