Skip to content

Troubleshooting and the crash log

Diagnose common problems, read the crash log, and give support what it needs.

Most problems fall into a handful of shapes. Work through the likely cause before assuming the worst.

The crash log

Open Crash log from the home screen. It lists every error the app has recorded, with a stack trace, and you can filter to failures only.

You do not need to understand a stack trace to make it useful. Two things matter: when the entry was written, and the message at the top. An entry timestamped at the exact moment something went wrong is the thread to pull.

You can open the log folder from this screen, or clear the log once a problem is resolved so the next one is easy to spot.

A white screen after sleep

If the laptop sleeps, or the network drops, Windows can leave the till window open but blank. Opening the app again used to focus that same blank window.

The till now reloads that window on its own: after the computer wakes, after the graphics process dies, and when you launch the app while a blank window is already there. Selling does not need the internet. If the screen is still blank after it has tried a few times, close the window from the taskbar or with Alt+F4. A dead screen closes immediately instead of waiting for a confirmation the cashier cannot see. The crash log will contain a line that starts with “Reloading the till window”.

The app opens on the Licence screen

The trial or the core licence has expired. Nothing is lost. See Activating your licence.

A barcode will not scan

  1. Scan into the checkout search box and watch. A high beep means the product was found. A lower double beep, or digits that stay in the box, means the scanner is fine and the code is not on any product. On a touch till stay in barcode mode so the Windows keyboard does not cover the screen; tap the name icon only when you need to type.
  2. If nothing appears, it is the scanner or the cable. Try it in Notepad to confirm.
  3. If the digits appear but no product is found, put that code on the product — as the SKU if it is the base unit, or as an extra unit barcode if it is a pack size.
  4. For a scale label specifically, check Selling items by weight — the prefix and digit rules are separate from a live COM/TCP scale.

Nothing prints

See Receipt printer setup for the full sequence. In short: check Windows can print, check the printer is still selected in Settings, check the paper size, clear the Windows queue.

If one specific invoice will not print while everything else does, and you use ZATCA Phase 2, check its ZATCA status. Uncleared standard tax invoices are deliberately held back.

A ZATCA submission failed

Open the document from Documents, read the error the platform returned, and use Retry.

If it keeps failing, work down this list:

  • Is the machine online?
  • Is the system clock right? Invoice timestamps are signed.
  • Do the seller details in Settings exactly match your ZATCA record?
  • Is the Phase 2 module still licensed and not expired?
  • Is the production certificate still valid?

Filter Documents by ZATCA status failed to see whether this is one document or all of them. One is a data problem with that invoice; all of them is a connection, clock or certificate problem.

The customer display does not appear

See Customer-facing display. In short: extend the desktop in Windows (do not duplicate), turn the setting on, and use Preview on this screen if you only have one monitor. Closing the till also closes that window.

The live scale does not show a weight

See Selling items by weight. In short: match COM port or TCP host, baud and protocol to the scale menu, then use Read weight now. Leave the poll command empty if the scale streams; send W\r or the hex from the manual if it only answers when asked. Do not give the scale and the pole the same COM port.

The pole display is blank or shows garbage

See Pole display. Try the other command set (CD5220, Epson, or plain text), confirm 9600 8N1 unless you changed the pole menu, and use Send test lines. The pole needs power as well as the cable.

The cash drawer does not open

See Receipt printer setup. In short: the drawer must be wired to the receipt printer, Send an open pulse must be on, and Test kick must move the drawer before you rely on it. If a receipt prints but the drawer stays shut, try the other Epson pin or the hex from the printer manual. A Windows driver that cannot send RAW jobs will never kick the drawer.

The drawer does not balance

That is a process question rather than a fault. Work through Shifts and end of day: unrecorded income and expense (especially cash) are the most common cause, followed by an opening float that was estimated rather than counted.

The app is slow

  • Run optimise in Settings, outside trading hours, after taking a backup. A database that has been trading for a year accumulates slack.
  • Check free disk space. A nearly full disk slows SQLite badly.
  • If it is a specific screen over a wide date range, narrow the range.
  • Check the crash log for repeating errors — something failing in a loop will drag everything down.

Something looks corrupted

Run the health check in Settings. If it reports a problem, restore your most recent good backup rather than continuing.

Databases usually get damaged by the machine losing power with the app open. If that is happening regularly, the underlying fix is a UPS or teaching people to shut down properly.

Testing the checkout at till resolution

You do not need a POS panel. On a laptop open Settings → Appearance → Laptop till preview and pick 15″ POS · 1024×768 (the usual till). The checkout stays in a window and the totals, category strip, and keypad shrink so they still fit. Turn on This laptop (no till size) when you want fullscreen again.

Getting help

Include all of this and you will usually get an answer in one round trip rather than four:

  1. What you were doing when it happened, step by step.
  2. What you expected and what actually happened.
  3. Your version number, from About & License on the home screen.
  4. The relevant crash log entry, copied out.
  5. A screenshot, if there is anything to see.
  6. Whether it happens every time or just once.

For a ZATCA problem, add the document number and its ZATCA status.

Send it to the support address on the contact page.