Error codes

Every error code, what it means, whether retrying helps — plus the codes that appear as warnings rather than errors.

Every failure is a structured error: code (a stable machine code that does not change between versions), message (a technical description), retryable (whether retrying as-is is meaningful) and possibly details.

How to use them

Branch on code, never parse message — the text may change.
When retryable is true, retrying as-is usually succeeds (waiting for a user to confirm, a rate-limit window ending…). When false, change the parameters or the environment first.
A machine-readable catalogue is exported from @printlink/types: ERROR_CATALOG and errorCatalogEntry(code), always in step with this page.

import { PrintLinkClient, PrintLinkError, TransportError } from '@printlink/sdk';

try {
  await client.connect();
  await client.ensureAuthorized();
} catch (err) {
  if (err instanceof PrintLinkError) {
    switch (err.code) {
      case 'PAIRING_PENDING':   // normal: ask the user to accept, then retry
        break;
      case 'PAIRING_DENIED':    // the user refused: explain and offer to retry
        break;
      case 'PERMISSION_DENIED': // missing permission: send them to the console
        break;
      default:
        console.warn(err.code, err.message, 'retryable =', err.retryable);
    }
  } else if (err instanceof TransportError) {
    // Transport: not running / wrong port / refused — guide install or check the port
  } else {
    throw err;
  }
}

Authorisation and connection

Code	Meaning	Retryable
`PAIRING_REQUIRED`	Pairing has not been completed	No
`PAIRING_PENDING`	Permission requested; waiting for the local user (not a failure)	Yes
`PAIRING_DENIED`	The pairing request was refused	No
`PERMISSION_DENIED`	Beyond the granted permissions	No
`TOKEN_INVALID`	The token is invalid or was revoked	No
`ORIGIN_NOT_ALLOWED`	This origin is not allowed to connect	No
`ORIGIN_CATEGORY_DENIED`	This origin category is never allowed (`file:`, for example)	No
`REMOTE_SOURCE_DENIED`	The source device is outside the network allow-list	No
`REMOTE_NATIVE_CLIENT_DENIED`	A remote non-browser client without `Origin` was refused	No
`PROTOCOL_MISMATCH`	Client and PrintLink protocol versions differ	No
`RATE_LIMITED`	Too many calls; temporarily throttled	Yes
`AGENT_SHUTTING_DOWN`	The service is shutting down and is not accepting jobs	Yes

Printers and profiles

Code	Meaning	Retryable
`PRINTER_NOT_FOUND`	The printer does not exist or was removed	No
`PRINTER_OFFLINE`	The printer is offline; the job was not submitted	No
`PRINTER_BUSY`	The printer is busy	Yes
`CAPABILITIES_UNAVAILABLE`	Capabilities cannot be read right now	Yes
`NATIVE_SETTINGS_UNAVAILABLE`	This platform cannot open native settings	No
`PROFILE_INVALID`	The profile no longer matches the printer or driver	No
`PROFILE_NOT_FOUND`	No such profile	No
`PROFILE_PRINTER_MISMATCH`	The profile does not match the target printer	No

Print options

Code	Meaning	Retryable
`UNSUPPORTED_PRINT_OPTION`	An option exceeds the printer's capabilities	No
`INVALID_PAPER_SIZE`	Invalid or out-of-range paper size	No
`COLOR_NOT_SUPPORTED`	Colour is not supported	No
`DUPLEX_NOT_SUPPORTED`	Duplex is not supported	No
`TRAY_NOT_SUPPORTED`	The tray is unavailable	No
`RESOLUTION_NOT_SUPPORTED`	The resolution is not supported	No
`WINDOWS_DEVMODE_REJECTED`	The driver rejected that combination	No

Content

Code	Meaning	Retryable
`SOURCE_EMPTY`	`source.items` is empty	No
`SOURCE_TOO_MANY_ITEMS`	Too many items (max 50, of which at most 10 HTML)	No
`DOCUMENT_INVALID`	The template document failed validation	No
`DOCUMENT_SCHEMA_UNSUPPORTED`	Unsupported document schema version	No
`PDF_INVALID`	The PDF is invalid or unparsable	No
`IMAGE_DECODE_FAILED`	The image could not be decoded	No
`HTML_INVALID`	Invalid HTML asset, or wrong MIME / size	No
`HTML_SNAPSHOT_UNAVAILABLE`	This environment cannot snapshot web pages	No
`HTML_SNAPSHOT_TIMEOUT`	The snapshot timed out	No
`HTML_SNAPSHOT_TOO_MANY_PAGES`	One HTML item exceeded 50 pages	No
`FONT_NOT_FOUND`	A referenced font is unavailable	No
`RENDER_FAILED`	Rendering the final artefact failed	No
`ASSET_NOT_FOUND` / `ASSET_HASH_MISMATCH`	Asset missing / hash mismatch	No
`UPLOAD_INVALID`	Invalid or oversized upload	No
`PAYLOAD_TOO_LARGE`	The request body is too large	No
`CONTENT_EXPIRED` / `CONTENT_NOT_RETAINED`	Content expired / not retained	No
`PREVIEW_NOT_FOUND` / `PREVIEW_UNAVAILABLE`	No such preview / preview unavailable	No

Jobs

Code	Meaning	Retryable
`JOB_NOT_FOUND`	No such job	No
`JOB_CANNOT_CANCEL`	The current state cannot be cancelled	No
`SPOOL_SUBMIT_FAILED`	Submitting to the system print queue failed	No
`PRINT_FAILED`	Printing failed	No
`QUEUE_FULL`	The job queue is full	Yes
`AGENT_STOPPED_BEFORE_FINISH`	The service stopped before the job finished	No
`OS_SHUTDOWN_TIMEOUT`	The system shutdown wait timed out	No
`WINDOWS_SPOOLER_UNAVAILABLE`	The Windows print spooler is unavailable	Yes
`WINDOWS_PRINTER_ACCESS_DENIED`	Windows denied access to that printer	No

Scanning

Code	Meaning	Retryable
`SCANNER_NOT_FOUND` / `SCANNER_OFFLINE`	No such scanner / offline	No
`SCANNER_BUSY`	The device or this site already has a scan running	Yes
`SCANNER_CAPABILITIES_UNAVAILABLE`	The device returned no capabilities	Yes
`SCANNER_BACKEND_UNAVAILABLE`	No scanning backend is available	No
`UNSUPPORTED_SCAN_OPTION`	Parameters exceed the device's capabilities	No
`SCAN_DISABLED`	Scanning is switched off in settings	No
`SCAN_CONSENT_DENIED`	The user refused this scan	No
`SCAN_CONSENT_TIMEOUT`	Desktop confirmation timed out; the job was cancelled	Yes
`SCAN_SOURCE_EMPTY`	The feeder is empty	Yes
`SCAN_DEVICE_ERROR`	The device reported an error mid-scan (jam, cover open)	No
`SCAN_TRANSFER_FAILED`	Transferring the result failed	Yes
`SCAN_TOO_LARGE` / `SCAN_TIMEOUT`	Page, size or duration limit reached	No / Yes
`SCAN_NOT_FOUND`	No such job, or it is not this site's	No
`SCAN_CANNOT_CANCEL`	Already terminal; cannot be cancelled	No

System and devices

Code	Meaning	Retryable
`INVALID_REQUEST`	Malformed request	No
`METHOD_NOT_FOUND`	No such method	No
`UNSUPPORTED`	Not supported on this platform or version	No
`INTERNAL`	Internal error	Yes
`PORT_UNAVAILABLE`	The new port cannot be bound (the old service keeps running)	No
`PORT_MIGRATION_FAILED`	Listener migration failed and was rolled back	No
`LISTEN_SCOPE_BIND_FAILED`	An address in the chosen scope cannot be bound	No
`UNSAFE_CONFIG_REJECTED`	The configuration violates a security floor	No
`POLICY_LOCKED` / `POLICY_INVALID`	Locked by machine policy / invalid policy file	No
`DEVICE_NOT_FOUND` / `DEVICE_PAYLOAD_INVALID`	No such raw device / payload validation failed	No
`DEVICE_TRANSPORT_FAILED`	Device transport failed	Yes
`DEVICE_PROTOCOL_UNSUPPORTED`	Device protocol unsupported	No
`CONTENT_UNSUPPORTED` / `CONTENT_OPEN_FAILED`	Content cannot be shown safely / opening failed	No

The two remote-fetch errors

A failed remote fetch is REMOTE_FETCH_DENIED (the target is not public or violates a restriction) or REMOTE_FETCH_TOO_LARGE (the response is too large). Messages contain only the source category, never the address or full URL.

Warnings (not errors)

These appear in the warnings[] of a successful result. Show them to the user; do not treat them as failures.

Code	Meaning
`UNSUPPORTED_PRINT_OPTION`	The option is unsupported and was ignored or downgraded
`OPTION_IGNORED`	The driver discarded the option
`PAGE_LAYOUT_EMULATED`	A job-level `fill` was emulated in software
`PAGE_RANGE_CLAMPED`	The page range partly overflowed and was clamped
`MIXED_PAGE_SIZES_UNIFIED`	No paper given and content sizes differed; the largest was used
`PAPER_DEFAULTED`	No paper given and none could be derived; the printer default was used
`MEDIA_TYPE_UNVERIFIED`	The printer reports no media types, so the value cannot be confirmed
`BINDING_MISSING`	A template placeholder has no matching data path
`BINDING_VALUE_INVALID`	An image binding value was invalid; the static image was used
`HTML_SNAPSHOT_UNAVAILABLE`	The web snapshot is unavailable (as a warning)
`HIPRINT_*`	Hiprint conversion downgrades, see Hiprint templates

How to use them

Authorisation and connection

Printers and profiles

Print options

Content

Jobs

Scanning

System and devices

Warnings (not errors)

See also

Troubleshooting

Permissions

Logs & log bundle

On this page