Troubleshooting

Real problems an operator can hit at the register, what each one means, and how to resolve it. Start with the quick reference, then jump to the matching section; if you end up contacting support, gather the details listed on Telemetry and diagnostics first.

Quick reference

Symptom	Likely cause	Fix
Scan does nothing	The register lost keyboard focus	Click the register search box, then scan again
"Register in use" / "Lease lost"	Another browser page owns the terminal	Close the other page, reopen as the same user, or supervisor takeover
"The changes cannot be saved... not up-to-date"	Concurrent write to the same record	Refresh; if it recurs, capture the AL call stack top line and update the app
"Terminal ... already has an open shift"	A half-created shift row	Press Open Shift on the existing card
Shift Expected Cash is empty	Sales rung without an open shift, or Blind Close is on	Open a real shift first; check the Blind Close setting
End of Day: item not mapped	A sold POS item has no BC item mapping	Map it on POS Items, run End of Day again
Settlement entry shows Failed	Payment could not post or apply	Fix the cause, then Post Pending Settlements
Card dialog seems stuck at the end	Completion waits for you	Press Done; if interrupted, use EFT Attention - never charge again
Receipt did not print	Transport, pairing, or destination problem	POS Print Jobs -> Retry, then Process Print Queue
Drawer will not kick	Transport has no ESC/POS channel	Use a WebUSB, LAN, or PrintNode destination
Scale will not connect	Browser, permission, or serial settings	See the scale section below
On Account is greyed out	No postable BC customer on the sale	Attach a mapped customer first
Return picker shows nothing	Wrong source sale selected	Both same-day and posted sales are offered; pick the exact sale
Register will not open (license)	Trial ended, license expired, or terminal cap	Open the POS License page

Scanner focus: a scan goes nowhere

The register keeps a scan box focused so a hardware scanner can type into it. If you clicked elsewhere (or the page just loaded), the keystrokes go nowhere - click the register's search box, then scan again. If a scan adds the wrong thing or nothing, see Barcode scanning for how unknown, duplicate, and expired barcodes are handled.

"Register in use" / "Lease lost"

Register in use means another unexpired browser page owns this store and terminal. Lease lost means this page used to own it, but a newer owner took over. In both states the page fails closed: the visible basket is orientation only and no mutable work can be sent.

• The other page is available: finish or park its work and choose Close Register there - the lease is released immediately.
• You lost or closed your own browser: reopen the register as the same Business Central user. The abandoned page is replaced immediately (no waiting) and the cashier PIN is required again.
• A different user needs the terminal: wait for the configured Register Lease Timeout (default 120 seconds; configurable 60-600 under POS Setup -> Register Behavior), ask the owner to close, or use supervisor takeover.
• Work cannot wait: choose Supervisor takeover and complete the supervisor PIN authorization. Takeover grants page ownership only - it does not change the active cashier or unlock the till.

"The changes cannot be saved... not up-to-date" / "Sorry, we just updated this page"

A Business Central optimistic-concurrency error: something wrote the record after your page read it. Known causes inside the app have been fixed at root cause - make sure you are on the current version. If you hit a new variant, note the exact action and the top line of the AL call stack from the error details before refreshing; that names the write path for support.

"Terminal ... already has an open shift"

The platform inserted a half-created shift row (Status shows Open but Opened At is blank) before you pressed Open Shift. Press Open Shift on the existing shift card - it adopts that row as the real open shift. Any leftover never-opened rows on the POS Shifts list are inert and can be deleted. See Shifts.

Shift Expected Cash is empty

A sale is linked to the open shift when it completes - when the money enters the drawer. If sales were rung before a genuinely open shift existed, they never counted: open a real shift, then complete sales. If Expected is hidden entirely, check the POS Setup Blind Close setting - when on, expected amounts are deliberately hidden until the shift closes. See Cash movements for what else feeds expected cash.

End of Day: "POS Item ... is not mapped to a Business Central item"

Posting needs a BC item on every sold line. The item sold fine at the register but has no mapping, so its consolidation group failed to post - other groups still posted. Open POS Items, select the item, use Map to BC (or turn on Auto Map Items to BC), then run End of Day again; already-posted groups will not post twice. See POS items and catalog and Consolidated posting.

A settlement entry shows Failed

Under per-tender settlement, one tender's payment could not post or apply - most often because a consolidated order was only partially posted, so a full-amount payment would over-apply. The entry fails safely; other entries are unaffected. Open POS Settlement Entries, read the Error Message, fix the cause (post the rest of the order, or correct the settlement account), then use Post Pending Settlements. See Per-tender settlement.

Card payment problems

• Dialog seems stuck after approval: completion is deliberate - the dialog shows "Approved/Paid - press Done to continue". Press Done.
• Payment will not start: the tender is rejected before any money moves when it is inactive or unassigned, the provider configuration is incomplete, the reader is unavailable, or the operator lacks permission. Check the reader's power and network, then Stripe Terminal setup.
• Interrupted mid-payment: never charge the card again. Open EFT Attention and reconcile the durable transaction - see the recovery drill on Payment acceptance labs.

The receipt did not print

• WebUSB or LAN: open POS Print Jobs and inspect Status, Attempt Count, Last Failure Category, and Error Detail. Repair or re-pair the printer, use Retry on the Failed job, then return to the register and run Printer -> Process Print Queue.
• PrintNode: check the PrintNode Printer ID and that the API key is set.
• Kitchen job shows InteractiveOutputDeferred: deliberate - the browser fallback cannot open an interactive report automatically. Retry from POS Print Jobs as an administrator, or configure a silent transport (WebUSB, PrintNode, or BC Printer) for kitchen output.
• Drawer will not kick: only WebUSB/WebSerial, LAN, and PrintNode destinations can pulse a drawer - the Browser and BC Printer transports have no ESC/POS channel.

Pairing and the full transport matrix are on Printers and hardware setup; for kitchen stations, also check Multi-station kitchen routing.

The scale will not connect or stabilize

• No chooser appears: use Chrome or Edge on the HTTPS Business Central environment and click Connect Scale directly - Web Serial needs a secure origin and a real user gesture. If the chooser was cancelled, click again and pick the correct port.
• Connected but never stable: verify the terminal's protocol, baud, data bits, parity, and stop bits, then the stable-reading count and tolerance.
• Need to keep selling: manual gross entry is available only where policy exposes it; a weighted or price-embedded barcode never needs the live scale.

The staged verification flow is on Scale and weighed items lab.

On Account is greyed out

On Account posts to a customer's receivables, so the sale needs a customer mapped to a postable BC customer. Attach one via the Customer button first - hover the dimmed button to see the exact reason. Then select On Account, press Add tender (an empty amount takes the whole remainder), and OK. See On-account sales.

The Return picker shows nothing to return

Both same-day (Released) and posted sales are accepted as return sources - pick the exact completed sale. If the Return button itself is missing, the register action bar wraps to a second row; it sits next to Gift Receipt. See Returns and refunds.

The register will not open (license)

An Unlicensed or Expired state, or an exceeded terminal cap, blocks the register before login and blocks new sales - everything else, including posting existing sales, keeps working. An administrator resolves it on the POS License page. See Licensing and trials for the trial, grace period, and activation.