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.

Windows MSI install fails ("Access denied" / error 1603)

• Run the installer from an elevated prompt: right-click PowerShell or Command Prompt > Run as administrator, then msiexec /i PatchPilot-Agent.msi ENROLLTOKEN=ppen_....
• Error 1603 usually means a previous install is half-removed. Run msiexec /x PatchPilot-Agent.msi first, or remove "PatchPilot Agent" from Apps & Features, then reinstall.
• Capture a verbose log for support: msiexec /i PatchPilot-Agent.msi /l*v pp-install.log and attach the last 100 lines.
• Some EDR/AV products quarantine new services on first run — check your EDR console and allow-list the PatchPilot Agent service if it was blocked.

Windows 10/11 LTSC: third-party app commands fail

• LTSC editions ship without winget (no Microsoft Store). Patch management still works; third-party app install/update commands need winget bootstrapped manually.
• Install the App Installer offline bundle from Microsoft's winget-cli GitHub releases, then re-run the failed command. Official LTSC support for app commands lands in v1.1.

macOS: installer blocked by Gatekeeper

• The macOS agent is a v1.0 preview and is not yet notarised. If macOS blocks it, go to System Settings > Privacy & Security and click Open Anyway next to the PatchPilot entry.
• The curl installer must run with sudo — it installs a LaunchDaemon, which requires admin rights.
• Signed and notarised .pkg builds ship in v1.1.

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.