Chapter 11. Troubleshooting

11.1 Service & connectivity

Job not found after submitting (E_JOB_NOT_FOUND)? Jobs enter the queue after accepted; if a previous job is keeping the render thread busy (e.g. an extremely long document), later jobs queue up — confirm the service is alive with GET /api/version and check the recent-jobs list on the status page (http://127.0.0.1:8899/).

Port in use / service won’t start? After changing configuration an old process may still hold the port: on Linux check for leftovers with pgrep -x wxprint-server; on Windows check the service state in the service manager. Always run curl http://127.0.0.1:8899/api/version before testing to confirm which process you are talking to.

Code/config changes not taking effect? Precedence: CLI flags > environment variables > config.json; listen address and TLS changes need a service restart (the tray settings dialog reminds you).

WS won’t connect (401)? With a token set, WS must carry ?token= (or the SDK constructor’s token); REST also accepts the ?token= query parameter (for the preview component page).

HTTPS page can’t reach the service? Browser mixed-content restrictions: an HTTPS page must use https/wss — enable TLS (Section 3.5); the SDK switches to the TLS port automatically.

11.2 Print output

Printer list empty? Linux/macOS rely on CUPS: make sure lpstat -v lists printers and one is configured; on Windows check “Devices and printers”. WxPrint does not install or manage drivers.

Submitted successfully but nothing prints? Check in order: GET /api/jobs/{id} for the state and the error field (E_PRINT/E_PRINTER_OFFLINE carry details) → printer state (GET /api/printers) → the system queue (the CUPS web interface at http://localhost:631/jobs or the Windows queue window).

Overlay positions off?

1. Was the template designed in physical millimeters (background calibrated, Section 7.9)?
2. Printer calibration: print the calibration page, measure, and write the correction (Section 7.10) — mechanical repeatability of ±0.1~0.3mm is normal and absorbed by calibration.
3. Nudge an individual template on a specific machine with the template-level calibration_offset.

Windows print text looks fuzzy? Windows output is rasterized for GDI at 600 DPI by default; for some older printers, adjust the rasterization DPI setting. Linux/macOS hand vector PDF to CUPS and are unaffected.

Gaps between pages on continuous paper? Confirm the template has page.continuous: true and the page height equals the paper height; CUPS needs driver support for custom media (media=Custom.<w>x<h>mm) — some drivers require a named form registered in the system.

Want to stop a batch mid-way? POST /api/jobs/{id}/cancel: immediate while rendering; stops the remaining pages while printing (pages already fed cannot be recalled).

11.3 Templates & rendering

Variables render as blanks? Job warnings list unresolved variables (e.g. elements[3].text: variable remark not found). Check the data path spelling — the warnings list covers every miss.

HTML template styles not applied? The built-in engine supports a modern CSS subset (box model/tables/ flex/float, …) but not @page paged media or JavaScript — paginate with .wxprint-page-break and move any logic to the server-side data.

Long CJK paragraphs not wrapping / overflowing? The CJK segmentation dictionaries are built in (no extra data needed); if it still misbehaves, upgrade to the latest version. For overlay text overrunning its box use overflow: shrink (auto font shrink) or wrap.

Want to reuse an inline template? Inline submissions are not registered — upload via POST /api/templates first, then reference it by id.

Images not printing? src supports template-relative asset paths, http(s), and data: URLs; URL images obey the fetch size/timeout limits (10MB/10s), and private addresses need allow_private_url.

11.4 Deployment

Windows service and tray together? Technically possible but not recommended: service mode (LocalSystem) and the user session keep separate configuration directories, and two diverging configs get confusing. Pick one per machine.

Linux unattended server autostart? A user-level systemd unit needs loginctl enable-linger <user> to run without a login session; alternatively use a root-level unit or run in the console directly.

Other machines on the LAN can’t connect? Change bind to 0.0.0.0 (or a specific interface address); open port 8899 (and TLS 8898) in the firewall; enabling the token is recommended.

Tray icon missing (GNOME)? GNOME ships without SNI tray support by default — install the AppIndicator extension (ubuntu-appindicators). Without SNI the service still runs; manage it via the status page and the configuration file.

11.5 Known limitations

• No printer driver installation/management (relies on system-configured printers).
• No cloud printing or internet relay (positioned as local/LAN).
• The HTML pipeline supports neither @page paged media nor JavaScript.
• Table elements use fixed row heights and do not span pages in v1 (overlong rows truncate with a warning); use the HTML pipeline for long cross-page tables.
• add_ellipse (ellipse) is not yet available (planned for v2).
• No Lodop compatibility layer (feature parity only; manual migration via the mapping matrix).