Troubleshooting

Agent shows offline in the console

First, check the agent service is running on the device:

• Windows: Services » PatchPilot Agent. Status should be Running. Logs at C:\ProgramData\PatchPilot\logs\.
• Linux: systemctl status patchpilot-agent and journalctl -u patchpilot-agent -n 100.
• macOS: sudo launchctl list | grep io.patchpilot and sudo log show --predicate 'subsystem == "io.patchpilot.agent"' --last 30m.

If the service is running but the device still shows offline:

1. Confirm the device can reach https://patchpilot.co.uk/api/agent/os-checkin — outbound HTTPS on port 443.
2. Check for a TLS-intercepting proxy. The agent pins to the PatchPilot root certificate; a corporate proxy that re-signs traffic will break it. Add an exception or use a proxy bypass for *.patchpilot.co.uk.
3. If on Windows behind WPAD, verify netsh winhttp show proxy.

First inventory pass never completes

The agent runs the first inventory pass within ~5 minutes of registration. If it stalls:

• Windows: confirm winget is available for the SYSTEM account. On older Windows 10 builds, install the App Installer package via the Microsoft Store or the offline bundle.
• Linux: confirm jq and your package manager are reachable; some hardened images strip them.
• macOS: confirm Homebrew installed cleanly; the install script logs WARN: Homebrew installation failed if it didn't.

Patch deployment shows "Failed"

Open the deployment row to see the per-device failure reason. Common causes:

• Reboot pending — Windows refuses some updates while a reboot from a previous patch is queued. Reboot, then retry.
• Disk space — Windows Update needs ~10 GB free. Check the Posture tab.
• Vendor server unreachable — some third-party installers fetch payload from the vendor's CDN; corporate egress filters can block this.
• Signature mismatch — the agent verifies the installer's digital signature before running it. A failure here is logged and the patch is skipped (this is a security feature, not a bug).

Compliance evidence shows gaps you didn't expect

1. Open Compliance and click the failing control.
2. It will show the device(s) responsible and the specific signal that's missing.
3. Most often this is a posture signal that hasn't been collected yet on a recently-enrolled device — wait one collection cycle (default 6 hours) and re-check.

Webhook deliveries are failing

• Check Integrations > Webhooks > Delivery log for the HTTP response code your endpoint returned.
• Verify your endpoint validates the X-Patchpilot-Signature HMAC header against your webhook secret.
• Endpoints that return 5xx or time out are retried with exponential backoff up to 24 hours, then marked permanently failed.

"Token invalid" on enrolment

• The token was already used and rotated to a device token — generate a fresh one.
• The token expired (default 30 days from creation) — generate a fresh one.
• The token was revoked from Settings > API Keys.

Still stuck?

Email support@patchpilot.co.uk with:

• Your organisation name (not the device token).
• The device hostname and OS.
• The last 100 lines of the agent log.
• A screenshot of the relevant error in the admin console.

Or check status.patchpilot.co.uk for known incidents.