Troubleshooting
SDK says not_running
The agent isn't running on this computer, or it uses a different port. Run thermalink in a terminal and look for "listening on http://127.0.0.1:17777". The browser must run on the same machine as the agent.
forbidden_origin / 403
Run thermalink allow <exact origin>, with scheme, host and port and no path (e.g. https://pos.example.com, http://localhost:3000), then restart the agent. The agent log prints the exact origin it blocked.
The agent is running, but the SDK still can't reach it (permission_prompt / permission_denied)
Chrome 142+ and Firefox 153+ ask the user before a public website may talk to a program on the same computer. Until the user answers, requests hang; if they click Block, every request fails and the browser does not ask again. To the page that looks the same as "agent not installed", so use tl.status() instead of tl.isRunning() and show the right message:
permission_prompt: tell the user to click Allow in the prompt next to the address bar.permission_denied: the user has to undo it by hand. Chrome/Edge: click the icon left of the address bar → Site settings → set Apps on device to Allow (Chrome 142–144 call it Local network access), then reload. Firefox: Settings → Privacy & Security → Permissions → Device apps and services → Settings.
If your app runs inside a cross-origin <iframe>, the outer page must delegate the permission: <iframe allow="loopback-network; local-network-access" …>.
Managed fleets can pre-allow your site so nobody sees the prompt: Chrome/Edge policy LocalNetworkAccessAllowedForUrls; Firefox policy LocalNetworkAccess. Don't rely on LocalNetworkAccessRestrictionsTemporaryOptOut: Chrome is removing it (planned for Chrome 156).
Pages you open from http://localhost during development are not affected.
Job "printed" but no paper comes out (Windows)
- Check the queue: Settings → Printers → open the printer. A job stuck in "Error" usually means the printer is off, out of paper, or the USB port changed.
- Use the printer's own vendor driver, or the "Generic / Text Only" driver on the correct port. Thermalink sends RAW, so any driver that accepts RAW works.
Receipt prints narrower than the paper, or lines wrap / spill onto the next line
The printer's real width differs from what Thermalink assumed. Run thermalink calibrate <printer>, then save the widest fully printed bar: thermalink alias receipt "<printer>" --dots <N>. If an 80 mm printer only prints the 384 bar fully, it's set to 58 mm paper mode. Change the paper width in the vendor's utility (e.g. Bixolon Unified Utility, Epson TM Utility) or with its DIP switches to use the full 80 mm.
Garbage characters / ? instead of letters
Use image mode (the default), which draws text with a TTF font and doesn't depend on printer codepages. For other alphabets set fontFile to a font that contains them. In text mode, pick a codepage that contains your characters (cp858 for €, cp866 for Cyrillic). Some cheap printers number codepages differently; try cp437 and cp1252. Scripts that ESC/POS fonts can't show (CJK, Arabic, Urdu) should be sent as an image.
QR code or barcode doesn't print
In image mode (the default) Thermalink draws QR codes and barcodes itself, so they print on any raster-capable printer. In text mode, very old or very cheap printers may lack native QR support (GS ( k). Switch that printer to image mode.
Image is too dark / too light
Pass "dither": false, "threshold": 100..180 for logos with flat colours. Dithering (the default) is best for photos and gradients.
Network printer times out
Ping the printer and check it accepts raw jobs on port 9100 (most Epson, Star, Bixolon and Xprinter network models do). Increase timeoutSeconds for slow Wi-Fi printers.
macOS / Linux: lp failed
Add the printer in CUPS first (lpstat -e must list it). Thermalink sends with -o raw.
Port 17777 is busy
Set "port" in the config and pass new Thermalink({ url: 'http://127.0.0.1:<port>' }).
More docs: Quick start · Reference · Compatibility