Troubleshooting

Pick the problem closest to what you're seeing.

I can't log in

Likely cause: A wrong PIN, an account temporarily locked after repeated wrong attempts, or the shop account being suspended.
Fastest safe fix: Double-check the phone number and PIN carefully. If locked, wait 15 minutes, or ask an owner/manager to reset your PIN.
Deeper checks: Use the “Forgot PIN” link on the login page. Confirm you have internet connectivity — QayyimAI Web doesn't work offline.
When to contact support: If you see an “account suspended” message and don't know why.

Getting started with QayyimAI TENANT_SUSPENDED

I see a “permission denied” message

Likely cause: Your current role (cashier or employee) doesn't have permission for this specific action.
Fastest safe fix: Ask a manager or owner to perform the action, or to approve it if the action supports manager approval.
Deeper checks: Check the “Roles & permissions” guide to see exactly what your role allows.
When to contact support: If you're sure your role should allow this action.

Getting started with QayyimAI REQUIRES_MANAGER

A sale won't complete at POS

Likely cause: Insufficient stock on a cart item, an empty cart, a missing customer on a credit sale, or an insufficient payment amount.
Fastest safe fix: Read the exact error message shown — it names the precise cause (see the error code reference below).
Deeper checks: Check every cart item's stock, and that the correct payment method is selected.
When to contact support: If it keeps rejecting with no clear message.

Point of sale (POS)INSUFFICIENT_STOCK EMPTY_ORDER CUSTOMER_REQUIRED INSUFFICIENT_TENDER

A mixed-currency payment doesn't add up

Likely cause: An under-entered amount on one payment line, or no exchange rate set.
Fastest safe fix: Confirm the sum of every payment line (converted to one currency) equals or exceeds the sale total.
Deeper checks: Check the exchange rate in Settings — it must be set to accept a non-primary currency.
When to contact support: If the rate looks correct and the problem persists.

USD & LBP currency MISSING_EXCHANGE_RATE INSUFFICIENT_TENDER CHANGE_WITHOUT_CASH

I can't accept payment in the non-primary currency

Likely cause: The exchange rate hasn't been set in Settings yet.
Fastest safe fix: From Settings (owner or manager), go to Exchange rate and set it.

USD & LBP currency Settings & account MISSING_EXCHANGE_RATE

I can't complete a refund

Likely cause: The requested refund quantity/amount is more than what's still refundable on this sale.
Fastest safe fix: Check the sale's detail page to see what's actually still refundable (part of it may have been refunded before).
Deeper checks: Confirm you have the permission needed to perform a refund.
When to contact support: If the displayed “refundable” number looks wrong.

Invoices, quotes & refunds REFUND_EXCEEDS_ELIGIBLE

Trouble saving an invoice or quote

Likely cause: A total mismatch from having the document open in more than one tab, or a discount larger than the subtotal.
Fastest safe fix: Reload the page, re-enter the lines if needed, and save from a single tab only.
Deeper checks: Review the discount and tax value on every line.
When to contact support: If it keeps happening on the same document after retrying.

Invoices, quotes & refunds TOTAL_MISMATCH DISCOUNT_EXCEEDS_SUBTOTAL

Scanning a barcode doesn't find the product

Likely cause: The barcode isn't registered on this product, the product is inactive, or it's a barcode from a different shop.
Fastest safe fix: Search by name/SKU instead of scanning, and check the barcode registered on the product's detail page.
Deeper checks: Confirm the product's status is active on the Products page.
When to contact support: If the barcode is correct and registered but still isn't detected.

Products & inventory PRODUCT_UNAVAILABLE

Displayed stock doesn't match what's physically in the shop

Likely cause: A sale/transfer/adjustment that hasn't been recorded in the system yet, or an earlier counting error that was never corrected.
Fastest safe fix: Record a “physical count” stock adjustment from the product's detail page to match the real count — the difference is recorded clearly in the movement history.
Deeper checks: Review the stock movement history (product tab) to trace every prior movement.
When to contact support: If the discrepancy is large and recurring with no clear cause.

Products & inventory

I can't close the shift

Likely cause: The counted-cash field is empty, or trying to close an already-closed shift.
Fastest safe fix: Make sure the actually-counted drawer amount is entered before pressing close.
Deeper checks: Check the Shifts page to confirm a shift is actually open.

Shifts & cash drawer

Desktop won't sync

Likely cause: No internet connection, the device isn't assigned to a branch in a multi-branch shop, or the device was revoked.
Fastest safe fix: Check internet connectivity first, then check the “Sync Center” in Settings for the exact status message.
Deeper checks: If the shop is multi-branch, confirm this device is assigned to a branch from Branch Settings.
When to contact support: If sync keeps failing despite a healthy connection.

QayyimAI Desktop DEVICE_BRANCH_UNASSIGNED DEVICE_REVOKED

Desktop is running offline

Likely cause: This is normal, expected behavior — Desktop is designed to work fully without internet.
Fastest safe fix: Keep working normally — sales, inventory, and customers all work locally. Sync will happen automatically once connectivity returns.
When to contact support: Only if the outage lasts unusually long despite the shop actually having internet.

QayyimAI Desktop

A transaction was rejected on sync

Likely cause: Stock was no longer sufficient on the server by the time the transaction arrived, or a version conflict with another edit that happened in the meantime.
Fastest safe fix: Review the rejected transaction (it stays saved locally in a clear state, never silently lost) and decide to edit or cancel it.
Deeper checks: Check the item's actual current stock on the server.
When to contact support: If the rejection reason isn't clear from the error message.

QayyimAI Desktop DUPLICATE_TRANSACTION

Printer not found

Likely cause: The printer isn't plugged in/powered, or the printer bridge (Print Agent) isn't connected.
Fastest safe fix: Check the printer is plugged in and powered, and restart the bridge device if one is used.
Deeper checks: The underlying operation (sale/receipt) still completes without printing — it can be printed later once the connection is fixed.
When to contact support: If the problem persists after checking the physical connection.

Printing & hardware

Print Agent unavailable

Likely cause: The bridge software isn't running on the local machine, or its connection dropped.
Fastest safe fix: Restart the bridge software and confirm it's running in the background.
When to contact support: If it stays disconnected after restarting.

Printing & hardware

The receipt won't print

Likely cause: A disconnected printer, out of paper, or a print layout mismatched to the printer's width.
Fastest safe fix: Check paper and connection first, then the receipt size setting (58/80mm) in Settings.
Deeper checks: The receipt can always be reprinted later from the sale's detail page.

Printing & hardware

The receipt prints with a long blank tail, or gets cut off before the total/change line

Likely cause: The printer driver is using a fixed paper length instead of the automatic, content-based length the browser requests.
Fastest safe fix: In the print dialog, open the PRINTER's own settings (not the browser's) and look for a paper-size preset named something like “Receipt” or “Continuous Roll” instead of a fixed size like 80×200mm, and select it.
Deeper checks: If no continuous-roll preset exists in the driver's list, try a longer fixed size (e.g. 80×297mm) as a workaround — a blank margin remains, but nothing gets cut off.
When to contact support: If the issue persists after trying the printer's own settings.

Printing & hardware

Arabic text on the receipt renders incorrectly

Likely cause: A thermal printer that doesn't support Arabic fonts or right-to-left direction.
Fastest safe fix: Check your printer's compatibility with Arabic text — not every thermal printer supports it.
Deeper checks: Try printing to PDF from the browser to confirm the issue is the printer specifically, not the system.
When to contact support: For a compatible printer recommendation.

Printing & hardware

Barcode label printing issue

Likely cause: The label layout (A4 or thermal) doesn't match the paper actually loaded.
Fastest safe fix: Pick the layout matching your actual label paper from the label-printing page.

Printing & hardware

Barcode scanner not responding

Likely cause: The search field isn't focused (for a USB scanner), or camera permission was denied (for camera scanning).
Fastest safe fix: Click the search field first, then scan — or grant camera permission from the browser's settings.
Deeper checks: Try scanning another known-good barcode to confirm the scanner itself works.

Point of sale (POS)Printing & hardware

Desktop can't find an update

Likely cause: You're genuinely on the latest version, or no build has been published yet for your specific OS/architecture.
Fastest safe fix: Compare your current version number in Settings against the latest announced on the download page.
When to contact support: If you're sure your version is older than the announced one and no update appears.

QayyimAI Desktop NOT_NEWER NO_ARTIFACT_FOR_PLATFORM

Update download/install failure

Likely cause: Unstable internet during download, or a signature rejection (an intentional security message).
Fastest safe fix: Retry from a stable connection. Never proceed installing an update that shows a signature-rejection message.
Deeper checks: The app takes a full backup before any install — your data is safe even if the install fails.
When to contact support: If the download keeps failing repeatedly, or a signature rejection appears.

QayyimAI Desktop BAD_SIGNATURE

The app opens but can't connect to the server

Likely cause: No real internet connectivity, or a temporary server-side issue.
Fastest safe fix: On Desktop: keep working offline normally — sync will catch up automatically later. On Web: reconnect to the internet.
Deeper checks: Check the “Sync Center” (Desktop) for the last known connection status.
When to contact support: If the outage persists despite genuinely healthy internet at the shop.

QayyimAI Desktop Getting started with QayyimAI

An import was rejected or stalled

Likely cause: An expired import session, an oversized chunk, or file columns mapped incorrectly.
Fastest safe fix: Review the column-mapping step carefully, and start a fresh import with the same file if the session expired — already-committed rows won't be duplicated.
Deeper checks: Check the import log to see exactly which rows were rejected and why.
When to contact support: If the import log itself isn't clear.

Imports & exports SESSION_EXPIRED SESSION_BUSY OVERSIZED_CHUNK

A subscription/license-related issue

Likely cause: The account is suspended, or a Desktop device was revoked or exceeded the allowed device limit.
Fastest safe fix: Contact support — these matters typically need support-team intervention.
When to contact support: Always, in this case.

Settings & account TENANT_SUSPENDED DEVICE_REVOKED