Troubleshoot agents, printers and print jobs
Start with the job status and request identifier, then move outward through the printer, agent and source document. This order avoids repeated prints and usually isolates the failing layer quickly.
Collect the identifiers first
Record the external order or document number, CloudPrint print_job_id, printer_id, latest status, failure_reason and X-Request-Id. Do not create another job until you know whether the first request was accepted. If the original request can be retried, reuse the same Idempotency-Key.
The printer is missing or offline
Confirm that the local agent is running and connected to the same CloudPrint account. Check the printer in the operating system, then refresh the printer list. A renamed queue may keep the same CloudPrint identifier, so route by printer_id, not by the displayed name. If the agent is offline, fix its outbound network access before changing API code.
The API rejects the job
A 401 usually means an invalid or expired token; request a new token once. A 403 means the token lacks a required scope. A 409 can indicate an idempotency conflict or an unsupported route. A 422 means the payload or print options are invalid. A 415 means the uploaded format is not supported.
The job is pending for too long
Check whether the assigned agent and printer are online. Pending work cannot reach a disconnected location. Keep polling with a bounded interval and show operators that the job is waiting; do not hide the state behind an endless spinner or automatically submit copies.
The job failed after delivery
Read failure_reason and compare the document format and requested options with the printer capabilities. Typical causes include a missing PDF renderer, a RAW language the printer did not advertise, or unavailable system printing. For labels, also verify DPI, media dimensions, driver, queue and calibration.
Escalating to support
Provide X-Request-Id, print_job_id, approximate time, account, agent and printer names, document format, requested options and the visible failure reason. Do not send client secrets, access tokens or confidential document contents in a support message.
Production checklist
- Record job identifiers and failure reasons for support and monitoring.
- Use an outbound agent connection; do not expose printer ports to the internet.
- Store the stable printer identity instead of relying only on a display name.
- Handle terminal status, retry policy and duplicate-print protection explicitly.