Skip to content
Fexl Lite

Printing issues

Receipt printing breaks more often than anything else in a retail stack — printers go offline, OS updates change the default, USB devices reshuffle on a reboot. This page walks through the symptoms in roughly the order they happen, with the actual fix for each.

Updated 4 May 2026·For v2.2.0·5 min read

Before you start

Three things to confirm before diving in:

  1. You’re on the desktop app (Tauri), not the web app. ESC/POS thermal printing requires direct hardware access. The web app downloads a PDF instead — see ESC/POS printers for the full backend list.
  2. The printer is on, has paper, and the cover is closed. Lid switches kill print jobs silently.
  3. The printer’s path is set in Settings → Printer. An empty path falls through to the OS default, which is plain text — it can’t render barcodes or do ESC/POS formatting.

The receipt doesn’t print at all

Nothing happens when I press Print

Check 1 — desktop or web? The web build can’t open a USB device. If the cashier hits Print and a PDF downloads instead, that’s the web app behaving correctly — install the desktop app on the till machine.

Check 2 — Settings → Printer → Test Print If Test Print fails, the path is wrong. Re-pick the printer from the discovered list and save. On a fresh USB plug, the vendor:product pair sometimes changes between reboots.

Check 3 — Tauri logs Open the desktop app’s log file (~/.config/Fexl Lite/logs/ on Linux, ~/Library/Logs/Fexl Lite/ on macOS, %APPDATA%\Fexl Lite\logs\ on Windows). The line you’re looking for is [Receipt] Printing receipt for invoice: .... If it’s there but no paper came out, the printer is the issue. If it’s missing, the click didn’t reach Tauri — usually a permissions issue.

The receipt prints, but it’s blank

Cause — paper is upside-down, or the printer is in graphic-mode receiving plain text. Fix — re-load the paper roll right-side up. Run the printer’s self-test (usually hold Feed while powering on); if the self-test prints fine, it’s a paper issue, not the printer.

”USB printer not found” toast

Cause — the vendor:product ID at the saved path no longer matches a connected USB device. Common after a reboot, OS update, or unplug-replug cycle. Fix — Settings → Printer → re-pick the same printer from the discovered list. Save. Try Test Print.

The receipt prints, but looks wrong

Garbled characters or wrong language (especially Arabic)

Cause — code page mismatch. Fexl Lite emits UTF-8 bytes; the printer is in CP437 (default) or some other legacy encoding. Fix — change the printer’s code page in its self-test menu or web admin:

  • English-only stores — CP437 or PC850 is fine, but the printer must match.
  • Arabic stores — set the printer to CP864 or Windows-1256 depending on the model. Test the change with a few Arabic line items before you trust the till to it.
  • Mixed Arabic/English — UTF-8 mode if the printer supports it; otherwise pick the encoding that handles the language with the worst-looking characters and accept that the other will be a little off.

Receipt prints sideways or cuts off the right edge

Cause — paper width mismatch. Fexl Lite’s ESC/POS path uses RECEIPT_WIDTH = 48 (characters per line, designed for 80mm rolls). If your printer is loaded with 58mm paper, every line wraps wrong. Fix — Settings → Printer → set Paper width to match the roll. The 58mm setting uses 32 characters per line and rebalances the columns.

Prices and totals are misaligned

Cause — using a non-monospace font on the OS default fallback path, or the printer is doing automatic font substitution. Fix — for ESC/POS path, the receipt always uses the printer’s monospace ROM font; if it’s still off, the printer’s “compressed” mode is on — turn it off in the self-test menu. For OS default, switch to ESC/POS by configuring the path properly.

A wall of escape codes prints (^[!@, ^[!a, etc.)

Cause — the OS default fallback is sending ESC/POS escape sequences to a printer driver that doesn’t speak ESC/POS, so the bytes print literally. Fix — either configure the ESC/POS path explicitly (USB or network), or switch the OS printer driver to “Generic / Text Only”.

The cut doesn’t fire

Receipt prints, paper feeds, but doesn’t cut

Cause 1 — printer model doesn’t support a cutter. Many cheap thermal printers are tear-bar only. Cause 2 — auto-cut is disabled in firmware or in Settings → Printer.

Fix — turn Auto-cut off in Settings → Printer if your model lacks the cutter; tear by hand. If your model does have one, run the printer’s self-test with cut enabled to confirm the blade still works (paper jams or worn blades can fail silently).

Wrong content on the receipt

”Serial Number: 1689” instead of the real IMEI

Cause — pre-v1.6.100 regression: the BE enricher was stringifying serialized_items.id (a database primary key) and emitting it as if it were a serial number. Fix — update to v1.6.100 or later. #62 v1.6.100 The fix re-fetches the invoice by ID before printing so the real identifier field renders.

Change Due shows on a card-paid receipt

Cause — pre-v1.6.100 bug: the change-due line was emitted on every cash-tendered field non-zero, even when the payment was card-only. Fix — update to v1.6.100 or later. #58 v1.6.100 Card payments suppress the Change Due block on customer-print and thermal alike.

Split-payment rows don’t sum to the total

Cause — pre-v1.6.100 bug: split-payment rows printed pro-rated values that drifted from the gross paid. Fix — update to v1.6.100 or later. #59 v1.6.100 Each method now prints its net amount; per-method rows sum to the invoice total exactly.

Logo doesn’t print

Cause — logo image format unsupported (most thermal printers want monochrome BMP at the right resolution), or the logo isn’t uploaded. Fix — Settings → General → upload a 256×128 monochrome BMP or PNG. The receipt builder dithers automatically; very small or very large source images can come out muddy. If your printer doesn’t support raster images at all (some entry-level models), the logo silently drops.

Network-printer-specific issues

Network printer disappears after a reboot

Cause — DHCP lease expired and the printer got a new IP. Fix — pin the printer’s MAC to a static IP in your router. Update the IP in Settings → Printer.

Network printer hangs for 10–30 seconds, then errors

Cause — wrong port (Fexl Lite defaults to 9100; some printers use 515 or 631), firewall blocks outbound 9100, printer is on a different VLAN than the till. Fix — verify the port via the printer’s web admin (most have one at http://printerIP/). Open port 9100 outbound on the till’s firewall. For VLAN issues, the till and the printer need to be on the same broadcast domain.

Network printer prints, but slowly

Cause — congested wifi, large image (logo) flooding the link. Fix — wired the printer if you can. Resize the logo to a smaller monochrome BMP. If the printer is shared between multiple tills, expect a queue.

Things that aren’t a printer problem

”Printing isn’t loading” — the dialog won’t open

This is a frontend issue, not a printer issue. Check the browser console (web) or the desktop app’s logs (Tauri). Most likely the invoice payload failed to load — a sync issue, not a print issue. See Sync issues.

”It prints, but the customer says the receipt is wrong”

The receipt reflects the current state of the invoice. If the customer received a refund since the original sale, the re-printed receipt shows the refunded total — that’s correct. To see the original sale’s amounts, look at the JE block on the General Ledger, or print the invoice detail PDF (which can show line history).

Still stuck?

  • Try the OS default fallback. Clear the printer path in Settings → Printer, hit Test Print. If a plain-text receipt comes out, your printer is fine and the ESC/POS path needs configuring. If even the OS default fails, the OS or the printer is the issue.
  • Check the ESC/POS printers page for the full path-discovery flow and supported drivers.
  • Open a support ticket with: (a) printer model, (b) connection type (USB / network), (c) the exact path string from Settings → Printer, and (d) the last 50 lines of the desktop app log.