Appearance
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) | Set Delivery region to Postal Code and add the customer's postal code |
| 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 |
By Feature
Order Capacity
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. 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:
markdown
### 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 issueError 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 |
| "Address is not within the delivery area. Postal codes supported: {postalCodes}. Postal code given: {postalCodeGiven}" | Postal code outside the delivery region | Add the postal code in Online Ordering → Delivery |
| "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