Troubleshooting Index

Common issues and solutions organized by feature.

Quick Reference

Most Common Issues

Issue	Feature	Quick Fix
No available time slots	Order Capacity	Increase orders per slot limit
Delivery not available	Online Ordering → Delivery (/online/online-ordering)	Add or widen a delivery area covering the address, and check no "do not deliver here" area sits above it
Item showing sold out	Inventory	Restock or disable tracking
Payment failing	Payments	Check the location's Payment Profile is active and validated (Settings → Payments), and that test mode is off for live orders. Stripe API keys are platform-level, not merchant-configurable
Menu not showing	Menus	Check the menu's status is Published and its visibility includes the target channel
Kiosk blank screen	Devices	Assign a device profile with a default menu — menus reach a kiosk via the profile, never the device
Tickets/receipts not printing, printer looks fine	Printers → LAN print bridge	Check which device holds the bridge (POS → Settings → Print bridge). If the holder is on another network, nothing prints and the error misreads as "printer-busy". Close the POS app on that device
POS Send fails and the order stays unsent, or Pay/Void says "The last kitchen send on this order is not confirmed by the fiscal module yet"	POS → fiscal write-ahead	Press Send again. The same fiscal transaction is resent and the fiscal module deduplicates it, so nothing is signed twice. Then pay or void
Settle says "This register does not take this payment method" or "This issuer is not set up for this payment method at this location"	POS → several tenders	The location's pos_tenders block does not enable that tender or list that issuer (location settings; no Back Office screen yet). Cash is always taken
Back Office payment breakdown shows Card or voucher rows next to Cash for POS sales	Reports → several tenders	Expected: a split POS sale is counted per tender, each leg in its own row (backend #2384, unmerged)

---

By Feature

Order Capacity

• No available time slots
• Kitchen overwhelmed despite limits
• Orders rejected unexpectedly

Online Ordering

• Location shows "Currently closed"
• Minimum order error
• Scheduled order not available
• ASAP not working

Delivery (Online Ordering)

Delivery region and delivery fee are a section inside Online Ordering at /online/online-ordering — there is no separate Delivery Zones page. The region is an ordered list of delivery areas, and the first area that matches an address decides both coverage and price. See Delivery Region.

• Address outside the delivery area
• Wrong delivery fee shown
• Delivery time estimate incorrect

Menu Items

• Item not appearing on menu
• Price not updating
• Image not showing
• Allergens not displaying

Modifiers

• Required modifier not enforcing
• Price not adding correctly
• Max selections not working

Payments

• Card payment failing
• iDEAL not showing
• Refund not processing
• Webhook not receiving

Loyalty

• Points not earning
• Points not redeeming
• Balance incorrect

Devices

• Kiosk not connecting
• KDS not receiving orders
• Printer not printing

---

Troubleshooting Template

Each issue should include:

### Problem: [Issue Description]

**Symptoms**:
- What the user/customer sees
- Error messages

**Possible Causes**:
1. First possible cause
2. Second possible cause
3. Third possible cause

**Diagnostic Steps**:
1. How to identify the cause
2. What to check in backoffice
3. What to check in logs

**Solutions**:

**For Cause 1**:
1. Step to fix
2. Step to verify

**For Cause 2**:
1. Step to fix
2. Step to verify

**Prevention**:
- How to prevent this issue

---

Error Messages Reference

Online Ordering Errors

Error Message	Cause	Solution
"Currently Closed" / "Currently Closed for Orders"	Outside business or ordering hours	Check business hours config
"Your selected time is no longer available for this order. We've suggested the nearest available time — please review and confirm."	Capacity reached for that slot	Choose a different time or increase capacity
"Minimum order amount of {CURRENCY} {amount} not met." (e.g. EUR 15.00)	Order below minimum	Add more items or adjust minimum
"We do not deliver to this address."	No delivery area covers the address, or an exclusion area matched first	Add or widen a delivery area, and check the order of the list — only the first matching area has a say
"Please enter your house number."	A street was picked from the merchant's list but no house number was given	Enter the house number (kept to 20 characters)
"This address is outside the delivery area."	Same causes as "We do not deliver to this address." above, but refused when the order is placed rather than while the customer types	Add or widen a delivery area, and check the order of the list — only the first matching area has a say
"Out of Stock"	Stock = 0	Restock item
"Invalid promo code"	Code wrong/expired	Verify code in Offers
"Location not found"	Payment Profile not validated	Complete Payment Profile validation in Settings → Payments

Storefront strings come from zestidoo-online-ordering/src/plugins/i18n/locales/en.ts (currentlyClosed, currentlyClosedForOrders, timeslotNoLongerAvailable, addressNotWithinDeliveryArea, outOfStock, invalidCode); the minimum-order message is raised by the backend in OnlineOrderingOrchestrator.

Kiosk Symptoms

The kiosk does not display fixed error strings for these cases, so they are listed as symptoms rather than quotes. Literal kiosk copy lives in upvendo-kiosk/src/plugins/i18n/locales/en.ts.

Symptom	Cause	Solution
Kiosk shows no menu	No device profile assigned, or the profile's default menu is unset / not Kiosk-visible	Device Management → Devices → assign a profile; Device Management → Profiles → set the default menu; Menus → include the Kiosk channel. See Kiosk Not Showing a Menu
Kiosk cannot take card payment	Terminal offline or not paired to the device	Check terminal connection and the device's terminal ID
Order submission fails	API error	Check network/backend

Backend Errors

Error Code	Meaning	Solution
400	Bad request	Check request data
401	Unauthorized	Check authentication
402	Payment required	A kiosk/KDS device has no active subscription — check the device's subscription
403	Forbidden	Check permissions
404	Not found	Check resource exists
422	Validation error	Check field values
429	Too many requests	Customer order-history (5/min) or order-detail (10/min) rate limit
500	Server error	Check backend logs
503	Service unavailable	Unconfigured webhook secret, or a failed dependency in the /health check — not a capacity signal

---

Diagnostic Tools

In Backoffice

• Activity Log: See recent changes
• Transactions: Check order history
• Reports: Analyze patterns

In Browser

• Network tab: Check API calls
• Console: Check for errors
• Application tab: Check local storage

In Backend

• Laravel logs: storage/logs/laravel.log
• MongoDB queries: Check slow queries
• Queue jobs: Check failed jobs