Troubleshooting

Common symptoms, what causes them, and how to fix them.

The admin loads a blank white screen

1. Stale cached bundle after an upgrade. The browser is holding the previous application bundle. Hard-reload with Ctrl+Shift+R (Cmd+Shift+R on macOS). If that doesn't clear it, clear the site's cache under System → Clear Cache and reload again.
2. PHP error before the app mounts. Set Error Reporting to Maximum in System → Global Configuration → Server, reload, and read the message. Revert the setting afterwards.
3. JavaScript error in the console. Open your browser's developer tools (F12) and check the Console tab. An error naming a missing asset usually means the media files did not deploy — reinstall the package over the top.
4. The system plugin is disabled. Check System → Manage → Plugins for nextrestaurantsession and confirm it is enabled.

A nav item I expect is missing

1. The module is switched off. Check Apps. A disabled module hides its nav item and refuses its endpoints. Note the dependency chain — orders requires menu, and kds, pos, delivery and corrections all require orders, so switching off orders greys out four more.
2. Your role doesn't grant the feature. Nav items are filtered by permission. Check Settings → Roles & Permissions for the role assigned to your user, and confirm it has at least view on that feature.
3. You're looking at the focused nav. Some screens collapse the navigation to the current working set. Return to the dashboard to see the full navigation.

Bookings show no available slots

1. Opening hours aren't set for that day. The availability engine only offers slots inside the location's opening hours. Open Locations → (your venue) and check the day in question — a day with no hours produces no slots, correctly.
2. No tables are defined. Availability is computed against real table capacity. If Reservations → Tables is empty there is nothing to book. Add tables with their seat counts.
3. The party size exceeds every table. A request for eight covers finds nothing if the largest table seats six. Add a larger table, or combine tables in your floor plan.
4. Everything is already booked. Check Reservations for that date — the engine is refusing because the tables are genuinely taken.
5. Wrong timezone. If slots appear shifted by hours, check the location's timezone and Joomla's own Global Configuration → Server → Website Time Zone.

Orders aren't reaching the kitchen display

1. The KDS module is off. Check Apps — and remember kds depends on orders.
2. No routing rule matches. Lines with no matching rule land on the default station. If a station's board is empty, check Kitchen → KDS Routing and confirm a rule sends that category, item or order type to it.
3. The board is filtered to another station. The KDS screen shows one station at a time; check which one is selected.
4. The order isn't in a kitchen-bound state. Orders that are still open carts, or that were cancelled before firing, never reach a station.

A payment didn't complete

1. The guest closed the browser at the provider. This should self-heal — the provider's webhook confirms the capture server-side. Check Payments for the transaction; if it is there, the order settled.
2. The webhook can't reach your site. The provider needs a publicly reachable HTTPS URL. On a local or firewalled install the webhook never arrives, so redirect flows that lose the browser stay unsettled. Verify the webhook URL configured at the provider matches your live site.
3. Credentials are wrong or in the wrong mode. Confirm the gateway is configured with the right key set, and that the provider account and the gateway agree on live versus test mode.
4. The provider isn't enabled. Check Payment Gateways — a configured but disabled provider doesn't appear at checkout.

A staff terminal won't accept a PIN

1. The staff member isn't allowed on this terminal. Terminals can be restricted to specific staff or roles. Open Terminals → (the device) and check the restriction.
2. The terminal is bound to another location. A location-bound terminal refuses to act on a different venue. Check the terminal's location against the staff member's.
3. The device token is stale. If the terminal was unlinked, re-provision it — open the terminal record and re-link the device using its code.
4. Too many failed attempts. PIN attempts are throttled. Wait for the throttle to clear before retrying.
5. The terminals module is off. Check Apps.

Stock isn't depleting when items sell

1. The item has no recipe. Depletion is recipe-driven — a menu item with no linked ingredients has nothing to draw down. Open the item and add its recipe.
2. The inventory module is off. Check Apps.
3. Depletion is configured off for that channel. Depletion settings control which order channels draw stock. Check Settings → Inventory.
4. You're looking at the wrong location. Stock is per location. Confirm the order's location matches the stock records you're checking.

Nothing saves and a banner says the site is read-only

Demo mode is on. It refuses every write at the server, deliberately, so a demonstration cannot change anything. Turn it off under Settings → Demo Mode. See Demo Mode.

The storefront pages look unstyled

1. The stylesheet didn't deploy. The storefront ships one stylesheet for the whole public bundle. Reinstall the package over the top so the media files are refreshed.
2. Your template is stripping the asset. Some templates aggressively control which assets load. Check whether the template has a CSS combination or optimisation feature interfering.
3. A caching layer is serving the old file. Clear Joomla's cache and any CDN or page cache in front of the site.

Storefront links produce 404s

The storefront pages resolve against Joomla menu items. If the Menu or Order menu item doesn't exist — or was deleted, unpublished, or moved to a menu that isn't rendered — links to it break. Recreate the menu item under Menus → (your menu) → Add New Menu Item → Next Restaurant.

The same applies after uninstalling: Joomla leaves menu items pointing at a removed component, and they 404 until you delete them.

A QR code opens the wrong table, or an expired session

1. The code is printed from an old table record. QR codes are per table; if the table was recreated it has a new code. Reprint from the current table record.
2. The session expired. Guest QR sessions have a time-to-live. The guest scans again to start a fresh session — this is intended, so an abandoned phone can't order hours later.
3. The reservations module is off. QR sessions and dining tables live under the reservations module. Check Apps.

Still stuck

Collect the following before contacting support, so the first reply can be a fix rather than a question:

• Joomla version, PHP version and Next Restaurant version
• What you did, what you expected, and what happened instead
• Any message shown on screen, verbatim
• Any error in the browser console (F12 → Console) and in Joomla's error log

Email [email protected].