Kiosk Troubleshooting

Summary

This guide covers the common problems that come up on a paired kiosk tablet day to day, and what to do about each one. If the tablet has not been paired yet, see Pairing a Kiosk Device first.

Prerequisites

• The tablet has already been paired and normally lands on /time-clock when opened.
• You can reach a manager or owner if the issue requires changes in Settings - Kiosk Devices.

Steps

”You are offline” banner appears

1. The kiosk needs an internet connection to record clock actions. If the Wi-Fi or wired connection drops, an “You are offline” banner appears at the top of the screen.
2. Clock-in and clock-out actions do not work while offline. The kiosk does not queue them.
3. Check the tablet’s network indicator. Reconnect to Wi-Fi, or move the tablet within range of the access point.
4. When the tablet is back online, the banner disappears and clock actions work again.
5. If staff have been waiting, they can clock in normally - the time recorded is the time they tap, not the time they were standing in front of the kiosk.

”Photo capture failed” or camera does not open

1. If your garage uses photo verification, tapping a staff card opens a camera viewfinder. If the camera does not open, the kiosk shows a “Photo capture failed” or permissions error.
2. Check the browser has camera permission for this site. On most tablets, open browser settings, find the kiosk site, and ensure Camera is set to Allow.
3. Close any other apps that might be holding the camera (e.g. another tab with a video call).
4. Refresh the kiosk page. The camera should reinitialise.
5. If photo capture still fails, ask the manager to switch off photo verification temporarily in the time tracking settings so staff can keep clocking in. Re-enable once the camera is working.

”Check-in failed” red error banner

1. A red error banner with a Retry button means the server rejected the action. The most common cause is a duplicate clock-in (the system thinks the staff member is already clocked in).
2. Tap Retry once. If the action still fails, refresh the page.
3. If a staff member’s status looks wrong (e.g. shows “Not checked in” but they swear they clocked in earlier), open /my-time for that staff member or ask a manager to view the time entries report - the entries are usually there with a slightly different status.

”Session expired” overlay on a dedicated kiosk device

1. Dedicated kiosk tablets keep a long-lived session, but if the cookie is cleared or the kiosk device record is deactivated, the tablet will show a session-expired overlay.
2. The fix is to re-pair the tablet. Ask a manager to generate a new QR code and follow the steps in Pairing a Kiosk Device.

A staff card is missing from the kiosk grid

1. The kiosk only shows staff who have been enabled for time tracking.
2. Ask the manager to open Settings - Staff for that staff member and switch on the time tracking flag. The card appears the next time the kiosk page is refreshed.
3. If your garage has more than 10 staff, make sure you are looking at the right page - a search bar appears above the grid; type the first letters of the name to narrow it down.

Rapid taps register only one action

1. The kiosk has a 300ms debounce on taps to stop a single tap registering as two clock actions. If a staff member taps twice in quick succession, only the first registers.
2. This is intentional. Wait a moment between taps - the success overlay shows for four seconds and dismisses itself when done.

Photo verification is enabled but staff cannot find the camera button

1. If photo verification is on for the garage, the camera prompt appears automatically as part of the tap-card-to-clock-in flow. There is no separate camera button.
2. If the prompt is not appearing, photo verification might be off at the garage level even though the staff member has it on, or vice versa. Ask the manager to check the time tracking settings.

The tablet keeps falling asleep

1. The kiosk page does not actively keep the screen awake. If the tablet locks itself, staff have to wake it before tapping their card.
2. On most tablets, the OS settings let you set a longer screen timeout, or set the device to never sleep while plugged in. If the tablet is on a fixed mount, that is the right answer.
3. Some browsers also have a “keep screen on” extension or kiosk mode that can help.

Geolocation prompt keeps appearing

1. The kiosk records optional geolocation against each clock action for audit purposes. The browser prompts for location permission the first time.
2. Allow it once and the prompt stops appearing. If you decline, clock actions still work - geolocation is optional and does not block anything.

Break button is missing on a staff card

1. The amber Break button only appears when break tracking is enabled at the garage level and the staff member is currently checked in.
2. If the button is missing for a checked-in staff member, ask the manager to enable break tracking in time tracking settings.

Clock actions are slow

1. If clock actions take more than a couple of seconds, the network or the server is slow.
2. The kiosk shows a loading spinner during the action and a success or error overlay once it completes. If you see the spinner for more than 10 seconds, refresh the page and try again.

Expected Outcome

• Most issues fall into one of: network problem, camera permission, deactivated device, or rate limiting. None require staff to lose clock-in time as long as the manager can be reached to re-enable a feature or re-pair the tablet.
• For audit reasons, no clock actions are queued while offline - the tablet must be online when the action happens.
• If pairing is broken, the fix is always to generate a new QR code and re-pair.

Troubleshooting (quick reference)

Symptom	First thing to try
”You are offline” banner	Reconnect Wi-Fi
Camera will not open	Check browser site settings - allow camera
”Photo capture failed” toast	Close other camera apps, refresh page
Red error banner on tap	Tap Retry once, then refresh
Session expired overlay	Re-pair the tablet (ask manager for new QR)
Staff card missing	Manager enables time tracking on staff record
Tap registers once for two taps	Expected - wait for the four-second success overlay
Tablet keeps locking	Adjust OS sleep settings or use kiosk mode
Slow clock actions	Refresh; check internet speed

Notes

• The kiosk uses the device’s network for everything, so unreliable Wi-Fi will show up as slow or failed actions. A wired connection or a strong access point in the workshop is worth the small investment.
• The 5-minute single-use QR token, the 300ms debounce, and the offline-blocking behaviour are all there for audit reasons. They make the time records harder to fake but do mean a flaky network is more visible than it would be on a tolerant system.
• If a tablet is repeatedly running into problems, the simplest reset is to deactivate its kiosk device record in settings, generate a new QR code, and pair from scratch.

Permissions

• Day-to-day kiosk troubleshooting (refresh, retry, reconnect Wi-Fi) requires no special permission.
• Anything that touches kiosk device records, staff time-tracking flags, or feature toggles (photo verification, break tracking) requires the kiosk.manage or settings.access capability and is done by a manager.