Troubleshooting

Most problems in Bitta Retail POS leave a record you can act on: a failed print job, a card transaction that needs attention, a refund leg that did not finish or a posting group that failed. This page lists the common problems by symptom, with the cause and the fix, so a manager or administrator can recover without guessing. Each fix uses the recovery pages that ship with Bitta Retail POS.

Prerequisites

• Cashiers (BAA POS - User) can open Receipt Recovery and EFT Attention from the register's activities. Kitchen Recovery needs BAA POS - Supervisor or higher.
• POS EFT Transactions and Refund Recovery need BAA POS - Supervisor or BAA POS - Admin.
• POS Setup, POS Print Jobs and End of Day need BAA POS - Admin. See POS user permissions.

Where problems show up first

On the Bitta Retail POS Role Center, the Needs Attention group counts failed work for the current register: Receipt Recovery, EFT Attention and Kitchen Recovery. On the admin Role Center, Operational Attention counts EOD Backlog, Settlement Attention, EFT Needs Attention, Failed Print Jobs, Unmapped Active Items, Unmapped Active Customers and POS Users Needing Setup. Start from the cue that is not zero.

A receipt did not print

Cause: the print destination could not be reached or refused the job. The sale is complete either way; only the output failed.

1. On the Bitta Retail POS Role Center, choose the Receipt Recovery cue in Needs Attention. The page must be opened from a configured register; opening it any other way shows "Receipt Recovery must be opened from a configured register."

2. Review Last Failure Category and Error Detail for the failed job, and fix the printer or destination.

Then recover the output:

• Retry sends the same output again. If the app cannot tell whether the printer already received the job, it first asks "This output may already have reached the device. Retrying it can produce a duplicate copy. Retry anyway?"
• Create Reprint prints a new copy with the terminal's current print setup. WebUSB and LAN receipts must be started from the POS Register.

Administrators see failed output for every terminal on POS Print Jobs (in Troubleshooting on the admin Role Center). For printer setup, see Receipt printers.

Kitchen output did not print

Kitchen Recovery opens the same recovery page filtered to failed kitchen labels and tickets for the register, with the same Retry action. It is shown only when the register profile has kitchen printing on, a compatible kitchen route exists and the user has BAA POS - Supervisor or higher. See Kitchen tickets and labels.

A card or QR payment was interrupted

Cause: the browser closed, the session ended or the connection dropped while a Stripe Terminal or Stripe QR payment was in progress.

Do not charge the customer again. When the register opens, the app first resolves every card or QR payment left in flight on that terminal and shows "... in-flight card payment(s) from an earlier session were resolved." If it cannot resolve one safely, it shows "Some card payments need attention - review the POS EFT Transactions page." Cashiers see these rows in EFT Attention.

1. A supervisor or administrator opens POS EFT Transactions from Tell Me. The newest transactions are at the top.

2. Filter Needs Attention to Yes and read Attention Reason: it says why the app could not resolve the transaction and what to do.

To poll the provider again for every open transaction, choose Reconcile Open Transactions. Transactions still held by a register can only be resolved on that terminal, and the app tells you to open the POS Register there.

For a full recovery drill, see Test with the Simulated provider.

A refund did not finish

Cause: a refund to the original card or QR payment failed or was interrupted at the provider. Open Refund Recovery:

• Retry Provider retries only the incomplete provider leg, with its original key.
• Finalize Return completes the return locally once every provider leg has capture evidence.
• Start New Attempt creates a replacement attempt after a definitive provider outcome.
• Record Confirmed Refund records a refund a supervisor verified in the provider's dashboard.

See Returns and refunds.

New sales or the register are blocked by the license

Cause: the license state is Unlicensed or Expired, or there are more active terminals than the license allows. Only two things are blocked: creating a new sale and opening the register. Viewing data, posting existing sales, End of Day and reports keep working. The Trial and Grace Period states do not block anything by themselves.

The cashier sees "Your Bitta Retail POS trial has ended. Open the POS License page to activate your subscription." or "Your Bitta Retail POS license has expired. ...". For too many terminals the message reads "You have ... active POS terminals but your plan licenses .... Deactivate a terminal on the POS Terminals page or upgrade your plan on the POS License page." Open POS License to check the state and act. See Pricing and licenses.

Setup is not ready

In the setup wizard, the Business Central Readiness step shows one row per check: Cash Customer, Posting Groups, Location, Tax Configuration, Payment Methods, Tender Settlement, User Mapping and Number Series. A row reads Ready, Configure later, "Needs attention - choose the assist button" or the exact failure. Choose the row's assist button to fix it; required rows are rechecked on Finish. See Run the setup wizard.

After setup, Validate Setup on POS Setup rechecks the four POS number series and, when Auto Create Cash Customer is on, that a cash customer is set. It does not recheck tax, tenders or users.

Register in use on another page

Cause: each terminal's register can be open on one page at a time. A second page shows "Register ... is currently in use on another page." A page that lost ownership shows "This page no longer owns register .... Retry or ask a supervisor to take over."

• Choose Close Register on the page you are leaving; it releases the register at once.
• An abandoned page keeps the register until Register Lease Timeout (sec) on POS Setup passes after its last heartbeat: 120 seconds by default. Values from 60 to 600 apply; 0 or any value outside that range uses 120. Then choose Retry.
• If work cannot wait, choose Supervisor takeover and enter a supervisor's PIN. Takeover locks the register, so the cashier signs in with a PIN again.

A PIN prompt is locked out

Cause: as many wrong PINs in a row as Max PIN Attempts allows (default 3; 0 means unlimited). Supervisor approval then shows "Too many supervisor approvals were entered incorrectly from this Business Central user. ..." for Approval Lockout (min.) minutes (default 15; 0 means until cleared). The lockout applies to the Business Central user, so cashiers who share one account are all locked. An administrator can end it at once with Clear Approval Lockouts on POS Setup. See Cashier PIN security.

A shift will not close

Symptom: Close Shift stops with "Shift ... cannot close while POS sale ... is still Open." and names a sale.

Cause: Close Shift refuses while any sale stamped with the shift is still Open, and the register's own current sale is stamped with the open shift even when it has no items.

Fix: Choose Show POS Sale to see which sale it is, and complete or cancel any parked basket or sale with items. If the sale named is the register's current sale with no items, leave the shift open and give the shift number and the sale number to Bitta Apps support. See Close the shift.

End of Day posted some groups and failed others

Cause: usually a mapping gap. Each completed sale keeps a frozen snapshot of its Business Central customer and items, and End of Day posts from that snapshot, never from the current mapping. A line sold while its POS item had no Business Central item fails its consolidation group with "Line ... in POS sale ... is not mapped to a Business Central item in its frozen snapshot." Sales with no customer are skipped. Other groups still post, and the summary reads "End of day finished with issues. Groups posted: ... Groups failed: ... Sales skipped (no customer): ...".

Check Unmapped Active Items and Unmapped Active Customers in Operational Attention, and map the records on POS Items or POS Customers (for example with Auto-Map to Business Central) so new sales freeze the right mapping. Mapping a record later does not change a sale that is already completed, so running End of Day again does not clear that group by itself.

To correct a completed sale that is not posted yet, you can reopen it at its register only while the sale's own drawer shift is still open: choose Sales on the register, pick the sale and confirm. Only the cashier who completed the sale can reopen it, Allow Cashier Sale Cancel must be on in POS Setup, the register profile must allow Cashier Cancellation, and a sale with a captured card or QR payment cannot be reopened. On the reopened sale, remove the affected line and add the item again so the line takes the new mapping, then tender and complete the sale, and run End of Day again; groups that already posted do not post twice. With the default EOD Open Shift Policy (Block), End of Day runs only after the shifts are closed, so a sale that failed this way usually cannot be reopened: contact Bitta Apps support. If an error offers to open POS Posting Claims, choose Recover there. See End of Day posting and Consolidated posting.

The connection to Business Central dropped

Bitta Retail POS is online only: it does not work offline and does not queue sales to send later. Reconnect, then reopen the POS Register. Any card or QR payment that was in flight is resolved when the register opens, as described above. To collect evidence for support, see Audit and telemetry.

Check the installed version

Read the installed version before you contact support or build an extension against the app.

1. Search for Extension Management in Tell Me.
2. Find Bitta Retail POS by Bitta Apps, LLC in the list and read its version.

To install or update the app, see Quick start: set up the POS.

What's next

This is the last page of the guide. Keep All POS reports and Setups by store type at hand for day-to-day questions.