Run the quick health check
- Read the tray status. Connected uses the plain mark; offline uses the struck mark; not enrolled or signed out uses the mark with a dot.
- Open Computers in the console. Connected confirms a live agent session, while disconnected does not explain the cause.
- Open PrintHook locally and check Connection, Last connected, and Last error.
- Run
printhook-agent diag --data-dir <data directory>. It checks DNS, TLS, proxy, WebSocket, content storage, and the spooler, prints JSON, and exits nonzero when a check fails.
If the computer is offline
A DNS error points to name resolution, VPN, or split-DNS policy. A TLS error often means the machine clock is wrong or a TLS-inspecting proxy's root certificate is not trusted by the machine account. A proxy response of 407 means the service needs proxy credentials. Set HTTPS_PROXY, HTTP_PROXY, and NO_PROXY in the service environment, or use the explicit PrintHook proxy setting, then restart the service.
The agent needs outbound port 443 to the PrintHook API, WebSocket endpoint, content storage, and update host. It does not require inbound access. If a proxy blocks WebSocket CONNECT, the computer remains offline and diagnostics identifies the ws_preflight stage.
If the computer connects but printers are missing
Verify the queue outside PrintHook using the same account as the service. On Windows, check an elevated Get-Printer; per-user printers may be invisible to LocalSystem. On Linux and Docker, run lpstat -p as the service user or inside the container. On macOS, confirm the queue exists in System Settings and CUPS. Fix discovery first, then wait for the next inventory update.
If jobs do not finish
Open the job timeline. A job held at queued has not reached a connected computer. A job held at sent_to_client or delivered needs attention on that machine. Inspect the operating system queue for paused printing, paper out, an open cover, or a driver dialog. A paused queue can be reported offline; on Windows, an oldest queued job waiting more than 60 seconds can also trigger an offline report. Review the agent log for the actual reason.
Review warnings on jobs that finish but look wrong. Media mismatch usually means the requested paper does not match the driver's form. Correct the queue default or the printer override. Do not resubmit repeatedly until you know whether the spooler accepted the first copy.
Export a diagnostics bundle
Choose Export diagnostics in the local app or run printhook-agent diag --export printhook-diagnostics.zip --data-dir <directory> on the computer. The bundle contains recent logs, a configuration copy with the key redacted, check results and timings, printer capabilities, the last 200 ledger rows without document content, service status, operating system details, and the installed version. The exporter omits document payload files, but logs and metadata can still contain sensitive names, paths, or URLs. Review and redact the bundle before sharing it.
Find logs and restart the service
The service log is C:\ProgramData\PrintHook\state\logs\agent.log on Windows, /Library/Application Support/PrintHook/state/logs/agent.log on macOS, and /var/lib/printhook/state/logs/agent.log on Linux or Docker. Restart with Services or Restart-Service PrintHookAgent on Windows, launchctl kickstart -k system/io.printhook.agent on macOS, sudo systemctl restart printhook-agent on Linux, or docker restart printhook-agent for Docker. If the issue remains, email support with a short error description and the UTC timestamp. Review diagnostics before sharing and ask how to transfer a bundle safely. Do not paste credentials or document content.