PrintLinkTroubleshooting
Nothing prints, it hangs, or the layout is wrong — the order to check connection, authorisation, printers, options and logs.
Last updated
Working through these steps in order covers the vast majority of cases. Each step says what to look at and what to do.
1. Is the connection up?
Look at: whether the page can connect.
const probe = await PrintLink.detect();
console.log(probe.installed, probe.reachable, probe.reason);| Result | What to do |
|---|---|
installed: false | PrintLink is not installed or not running; guide the user through installing or starting it |
installed: true, reachable: false | The service is down or the port is wrong — check the tray and the console's port setting |
| Both fine | Continue |
From a shell: curl http://127.0.0.1:17888/healthz returning 200 means the service
is up.
2. Has authorisation happened?
Look at: the error code.
| Code | Meaning | What to do |
|---|---|---|
PAIRING_PENDING | Waiting for the user to confirm locally | Ask the user; do not treat it as a failure |
PAIRING_DENIED | The user refused | Explain why and offer to request again |
PERMISSION_DENIED | Missing permission | Send the user to Security & sites to grant it |
TOKEN_INVALID | The token is no longer valid | Call ensureAuthorized() again |
ORIGIN_NOT_ALLOWED | The origin is refused by policy | Check the new-site policy and the trusted list |
3. Is the printer there?
const { queues } = await client.listPrinters();
const status = await client.printerStatus(queueId);| Symptom | Meaning | What to do |
|---|---|---|
| Empty list | The operating system has no usable printer | Make OS printing work first |
status.state: 'offline' | The printer is offline | Check power, connection, and whether another device holds it |
status.reasons shows paper/jam/door | A hardware condition | Fix it on the device and reset the panel |
Stuck in printing | The queue is stalled | Cancel that job from the console Jobs page and check the panel |
4. Were the options downgraded?
Validate before submitting rather than finding out after:
const check = await client.compose({ queueId }).paper('A3').addPdf(bytes).validate();
console.log(check.requested); // what you asked for
console.log(check.effective); // what will be used
console.log(check.warnings); // the differenceCommon warnings are listed under print options.
If the output is too small, cropped or misplaced, see image placement and size and the paper setting. Washed-out, grainy photos usually mean the media type is wrong.
5. Still wrong? Export a log bundle
The bundle records how the options were resolved step by step, the render and spool path, and the capability reads — far more detail than an error code. See logs & log bundle.
Quick lookup
| Symptom | Most likely cause |
|---|---|
| The page connects but nothing prints | Missing permission, or the printer is offline |
| Asked to authorise, but the user says they approved | Confirm they approved on the same computer; confirm the site is not paused |
| A LAN terminal cannot connect | Firewall, source allow-list, or browser mixed content — see LAN print workstation |
| One invoice printed twice | A double click; use an idempotency key, see print |
| Preview looks right, the print does not | Confirm you printed from that same preview session (printing from the preview does not re-render) |
| The queue fills with jobs | Check for a print() loop; use one compose() instead |
| Other people's jobs are in the queue | Check ownership with getJob; do not clear the queue to cancel a job |
When you need help
- Note the error code and the time it happened;
- Export a log bundle;
- The bundle contains no document content or tokens, so it can be shared per your organisation's policy.