Printing troubleshooting

Almost every printing problem has one of four causes: QZ Tray is not open, the certificate is missing, the paper size does not match the roll, or someone is trying to print from a tablet. Check those four in order first; if it is none of them, find your case below. This guide was verified with QZ Tray 2.2.6.

When the Printer card under Settings → Point of sale (/admin/settings/pos) cannot connect, it tells you exactly why and what to do. The Copy diagnostics for support button copies the technical information to paste into your message to support.

It says Disconnected and will not print

Check that QZ Tray is open in the Mac menu bar or the Windows system tray, next to the clock (it may be under the ^ arrow), and press Connect. The connection drops every time you reload the page; if you already have a printer configured, it reconnects on its own. If there is no icon, open QZ Tray from the Start menu or from Applications.

A security prompt appears every time I print

That computer is missing the certificate from step 2 of Install QZ Tray. It still prints if you grant permission, but it asks each time. Run the Setup wizard on that machine and the prompt goes away.

I installed the certificate and nothing changed

QZ Tray only reads the certificate when it starts. The installer restarts it for you, but if the prompt still appears when printing, quit it from its icon (right-click › Exit on Windows, Quit in the Mac menu bar), open it again and reload the La Comanda page.

To confirm the certificate is in place: right-click QZ Tray › Advanced › Diagnostic › Browse App folder…. That folder must contain the file override.crt. If it is not there, run the installer again.

With the certificate installed, the QZ Tray prompt says Verified and choosing Allow once is enough; it does not come back.

The printer list is empty

The list comes from your operating system, not from La Comanda. Install the printer's driver and print a test page from the system; the moment it shows up there, it shows up here. Then press the refresh button next to Receipt printer. If you see No printers found, the system has none installed yet.

The ticket comes out cut off or with overlapping text

That is the paper size. 58mm is 32 characters per line and 80mm is 48; pick the wrong one and text overflows or falls short. Change the Paper size in the Printer card and press Test print again.

It prints strange symbols or blank pages

This is almost always a printer that is not ESC/POS, or a generic driver that does not match it. Install the manufacturer's driver for your exact model and repeat the test. Which printers work is in Compatible printers.

I cannot find the option on the tablet

Thermal printing only exists on computers, because QZ Tray is a desktop program; on a tablet or phone you will see No printer configured. You can take orders on the tablet and let the register's computer print, with auto-print or with Print ticket on the kitchen display.

My antivirus or firewall blocks QZ Tray

QZ Tray listens locally on ports 8181, 8282, 8383 and 8484, and on 8182, 8283, 8384 and 8485. Allow the application in your antivirus or firewall: this is traffic inside the same computer and never leaves your network.

Windows says the file is not safe

That is the normal SmartScreen warning for a freshly downloaded file such as setup-printer.bat. Press More info and then Run anyway. Windows then asks for administrator permission in the blue User Account Control box: press Yes so the certificate can be copied.

Browser access to QZ Tray is blocked

Chrome and Edge ask for permission before a page can talk to applications on the same computer. If the card shows Browser access to QZ Tray is blocked, that permission was denied for La Comanda:

• If you installed La Comanda as an app, open ⋯ › App info › App settings.
• In a Chrome or Edge tab, open the site controls beside the address bar.

Allow Local network access or Apps and services on this device, reload La Comanda and try again. If the browser shows that prompt when you press Connect, accept it.

QZ Tray is not responding

If the card says QZ Tray is not responding, no local port answered. Make sure QZ Tray is open (its icon appears in the system tray or menu bar) and that antivirus or firewall software is not blocking it. Also try https://demo.qz.io on that same computer: if it cannot connect there either, the problem is in QZ Tray or that computer, not in La Comanda.

The request for QZ Tray could not be signed

Every print and every printer listing is signed first on La Comanda's server. If the card says The request for QZ Tray could not be signed, nothing was sent to QZ Tray and nothing was printed. The notice itself says why:

• Your session expired: sign in again and try again.
• Your account has no active restaurant: sign in again and try again.
• The signing service did not respond from this address: it may be down or that address is not authorized to sign. Copy the diagnostics and send them to support.
• The signing service failed on the server or answered something unexpected: try again in a moment; if it persists, copy the diagnostics and send them to support.

QZ Tray is open but La Comanda will not connect, even after reinstalling it

This is the case no browser setting fixes, and the card announces it as QZ Tray has La Comanda blocked. Symptom: QZ Tray open, no connection, even though you already reinstalled QZ Tray and restarted the machine. Cause: a saved Block in QZ Tray. It is fixed at that computer in about five minutes.

What happened

Every time a page wants to print, QZ Tray shows a security prompt. If Block was chosen in that prompt with Remember this decision checked, QZ Tray saved the decision in the user's folder, and since then it answers "Connection blocked by client" to every attempt. Reinstalling QZ Tray or restarting the computer does not clear it: the uninstaller cleans the program folder, not the user's. It is removed from QZ Tray itself, in under a minute.

QZ Tray keeps those decisions per user:

• Windows: %APPDATA%\qz\blocked.dat and allowed.dat.
• macOS: ~/Library/Application Support/qz/.
• Linux: ~/.qz/.

Right-click QZ Tray › Advanced › Diagnostic › Browse User folder… opens that folder.

Steps, in order

1. Open the QZ Tray menu. Find the QZ Tray icon in the system tray, next to the clock. If you do not see it, click the ^ arrow. Right-click the icon. If there is no icon, open QZ Tray from the Start menu and look again.
2. Open Site Manager. In the menu, go to Advanced and then Site Manager…
3. Remove the block. Switch to the Blocked tab. You will see the list Sites permanently blocked from access with the entry La Comanda (La Comanda POS). Select it and press the − button, or the Delete key. Close the window. If the tab is empty, check that Advanced › Block anonymous requests is unchecked.
4. Install the La Comanda certificate. In La Comanda go to Settings › Point of sale › Printer and open the Setup wizard. Download the installer, setup-printer.bat, and double-click it. In the SmartScreen warning press More info and Run anyway; in the blue User Account Control box, Yes. It is done when you see "Printer setup complete". If QZ Tray still asks when you print, quit it from its icon (right-click › Exit) and open it again: it only reads the certificate when it starts.
5. Confirm the certificate is in place. Right-click QZ Tray › Advanced › Diagnostic › Browse App folder… That folder must contain the file override.crt.
6. Open La Comanda again. Close La Comanda completely, whether the installed app or the browser tab, and open it again. In Printer press Connect. If Chrome asks about "Apps and services on this device", allow it.
7. If QZ Tray asks, choose Allow. With the certificate installed the prompt says "Verified" and never comes back.
8. Print the test. Select your printer from the list and press Test print. The test ticket prints and the status says Connected.

The same guide, with a drawing of the Site Manager window, is on the public page /en/impresoras/desbloqueo-qz-tray, meant to be opened on a phone while standing at the computer.

What does not help

• Deleting the whole %APPDATA%\qz folder. There is no need: just remove the entry on the Blocked tab.
• Reinstalling QZ Tray again. The block lives in the user's folder and survives the reinstall.

If Site Manager cannot be opened

Only in that case, edit the file by hand: fully quit QZ Tray (icon › Exit), back up %APPDATA%\qz\blocked.dat, delete only the line whose second column says La Comanda POS, and start QZ Tray again. To undo it, restore the backup.

What each notice on the Printer card means

If it still will not connect, send us this

Before changing anything else, gather this from the affected computer and write to us following Contact support:

1. The QZ Tray version: right-click the icon › About…
2. Which browser you use and whether you open La Comanda as the installed app or in a tab.
3. A screenshot of the notice La Comanda shows when you press Connect.
4. The text from the Copy diagnostics for support button, shown under the notice in Printer.
5. Screenshots of the Allowed and Blocked tabs in Site Manager, and whether Advanced › Block anonymous requests is checked.
6. Whether https://demo.qz.io manages to connect on that same computer. It uses QZ's own certificate, so it still connects when only La Comanda is blocked.
7. If you can, the QZ Tray log around one Connect attempt: right-click › Advanced › Diagnostic › View logs (live feed)… or Zip logs (to Desktop). The lines that matter are "Connection blocked by client", "Denied La Comanda POS to", "Bad signature on request", "Certificate is expired" and "Server started on port(s)". With the certificate properly installed you see "Successfully chained certificate: CN=La Comanda POS" and "Adding La Comanda (La Comanda POS) to allowed list".

The diagnostics the button copies include the page address, whether La Comanda runs as an app or in the browser, the browser permission states, the QZ Tray library version, the last error and the signing status. They contain no passwords, keys or sales data.