Troubleshooting

Troubleshooting

Real issues found and fixed during development, kept here because the symptoms are easy to misdiagnose as something else.

Camera scanning

"Camera doesn't open at all on my phone, but works on the till PC." This is almost always the secure-context restriction, not a bug — see Hardware Setup § Camera scanning over HTTPS. localhost and a LAN IP are not the same origin to a browser, even though it's "the same app."

"Camera opens, asks for permission, but doesn't detect the barcode." Two independent causes, both fixed in the current version — if you're on an old build, update:

• Low default camera resolution — fixed by requesting a 1080p frame explicitly.
• Focus locked once at stream start instead of continuously readjusting — fixed via best-effort continuous autofocus (not available on iOS Safari, which has no programmatic focus control at all; this is a real platform gap, not an app bug).

"A specific barcode type doesn't scan (e.g. a pharmacy DataMatrix code, a CODABAR coupon)." The scanner is configured to accept every format the underlying decode library supports by default — if a real product's code still doesn't scan, that's worth reporting as an issue rather than assumed to be a known limitation.

USB thermal printer

"Print via USB fails, but echo hi > /dev/usb/lp0 works fine from a terminal on the same machine." This is the standard case, not an edge case — see Hardware Setup § Direct-USB setup. Most generic 80mm printers are vendor-class USB devices; the kernel's usblp driver binds them (which is why the terminal echo works) even though a class-7 USB-Printer scan would find nothing. The app's primary transport is the same /dev/usb/lp0 character device the terminal test uses, specifically because of this.

"Works on Windows with the manufacturer driver, doesn't work over direct USB on Debian/Linux." The Linux kernel's usblp module auto-claims any USB Printer-class device on plug-in, which can block a libusb-based claim attempt with a "busy" error. Windows uses its own vendor driver and never hits this. The fix (already shipped) detaches the kernel driver before claiming the interface and reattaches it afterward.

"Check printer reports found even with nothing plugged in." This would be a real bug if seen — printer node creation and printer detection are deliberately different code paths (creating a /dev/usb/lp* node on demand doesn't mean a printer is behind it; the app probe-opens each node instead of just listing them). Report it if this ever shows a false positive.

Money / dues / store credit

"A customer's due balance won't fully clear — there's a tiny fractional amount left over even after paying in full." This was a real, fixed bug: floating-point balances maintained via database-side increments accumulate binary rounding residue across many transactions. Balances are now read-modify-write in application code, rounded to 2 decimals, and written with a plain set. If you ever see a due/credit balance that isn't exactly zero after a full settlement, that's worth reporting — it shouldn't be possible anymore, but the failure mode is distinctive enough to name here.

"I can't collect a standalone due payment from the POS screen without adding items to the cart." Fixed — the checkout screen allows finalizing a due-only collection (empty cart, dueToClear > 0) as its own zero-item invoice.

"Checkout finishes but the tab freezes/spins." On a machine with no browser-configured default printer, an auto-print setting using the browser print dialog (window.print()) can hang waiting on a dialog that has nothing to open. Set Settings → Receipt → Auto-print using → Direct USB if you're not printing through the browser, or turn auto-print off and use the Print/Download buttons manually.

GST / pricing

"The total charged is higher than the price I entered." Should not happen in the current version — GST is backed out of the entered price (treated as inclusive MRP), never added on top. If you see a total exceed sellingPrice × quantity before any discount, that's a real bug; please report it with the exact product price, GST rate, and any discount applied. See Architecture § Data & money model for the intended formula.

Network / LAN access

"App works on the till PC but not from another device on the same Wi-Fi." Confirm the other device is actually on the same LAN/subnet, and that nothing (a firewall, a guest-network client-isolation setting on your router) is blocking device-to-device traffic. If it's specifically the camera that fails while everything else works, see the secure-context note above — that's the far more common cause.

Still stuck?

Open an issue at Raktim94/nodedr-pos/issues with: which install method (Docker/.exe/.deb/CasaOS), OS, and browser; exact steps to reproduce; and, for hardware issues, the printer/scanner model if known. See Contributing for more on filing a good report.