Common problems

The installer says the host is not enrolled, or the token is refused

Create a fresh token on Enrollment and check it has uses left and has not expired. Enrollment also lists every attempted use of a token, with the reason it was refused (wrong network range, hostname not allowed, waiting for approval).
Some tokens need each new host approved: approve it on Enrollment.
On the hosted service, an organization at its device limit cannot enroll more hosts until a device is removed or the limit is raised.

A host shows Offline

A host is Offline after about three minutes without a check-in. It comes back by itself once it can reach the portal again. Check on the host:

# Linux
sudo systemctl status patchpilot-agent
sudo journalctl -u patchpilot-agent -n 50
# macOS
sudo tail -n 50 /var/log/patchpilot-agent.log

powershell

# Windows
Get-Service PatchPilotAgent
Get-Content "$env:ProgramData\PatchPilot\agent.log" -Tail 50

Most often the host cannot reach the portal's address on port 443 through a proxy or firewall: see Requirements and network access.

A job timed out

"The agent stopped reporting progress for 30 minutes" means the host went quiet in the middle of the job. Usual causes:

a laptop that went to sleep or was closed (keep it on power and awake while it patches);
the host lost its network or was switched off;
the agent was restarted while the job ran.

Run the job again once the host is online. A job that runs far longer than it should can be stopped with Stop job: see Patch a device. A Mac with an Intel processor can spend hours compiling Homebrew updates: leave Homebrew updates out of jobs for those Macs, or run them when the Mac can stay awake.

A job failed

Open the job on Jobs and read the host's output: the package manager's own error is there. Common ones:

Signing key warnings on Ubuntu or Debian: a third-party repository's key has expired or changed. Update the repository's key on the host as its vendor describes, then scan again. PatchPilot never skips signature checks.
Could not get lock (apt) or another package manager already running: someone or something else is installing at the same time. Wait and run the job again.
Not enough disk space: free space on the host; the pre-flight check reports how much is free.

An update is never installed

It is Held on host: the host's administrator pinned it.
A policy excludes it, or holds it as a major-version upgrade: see the reason in the policy's preview.
On an Intel Mac, policies leave Homebrew updates out on purpose.

Forgotten password: Forgot password? on the sign-in page sends a reset link.
Lost authenticator: an Organization admin opens them on Users, chooses Manage and Give a one-time sign-in pass…, and hands the pass over in person or by phone. They choose Have a sign-in pass? when asked for the second factor, then set up their authenticator again under My security.