Common Troubleshooting Issues
This guide covers common technical and operational issues that can arise in the setup using GEM, along with suggested causes and quick resolutions.
Dashboard
| Issue |
Possible Cause |
Resolution |
| Dashboard not loading |
URL error, server offline, or Docker down |
Verify URL, refresh browser, and check Docker container |
| Devices not showing in dashboard |
Network desync, headset off or idle |
Restart headset/app, wake headsets, check Wi-Fi or network status, try a different device - send to operator to load headset into Database |
| Device stuck in incorrect state |
Session not cleared, app crash |
Reset device state manually in dashboard-Send to Operator to review if state can't be changed in the dashboard. |
| Guest missing from onboarding |
QR code not scanned or scan failed |
Re-scan ticket; try a different device if needed |
| Groups are not automatically boarding |
Dashboard is set to Manual mode |
Confirm Manual mode is set to off, if this doesn't resolve, get logs and submit logs to GEM team |
NOTE:
To keep the flow moving, Device issues should not be debugged while onboarding groups. Devices should be put to the side and sent to technical operator for review.
Headsets & Experience App
| Issue |
Possible Cause |
Resolution |
| Headset not receiving assignment |
Not connected to server/Not in Database / poor Wi-Fi |
Reboot headset, check connection and app status |
| App stuck or black screen |
App crash or load error |
Relaunch app or restart headset |
| No “Device is unassigned” message |
No handshake with GEM server |
Verify server is live and correct build is installed |
| Sync issues between headsets |
Clock mismatch, server lag |
Reboot headsets, check time sync and latency |
| Poor tracking or orientation |
Sensor obstruction, low light |
Clean sensors, improve lighting, ensure room setup is clear, restart headset |
| Issue |
Possible Cause |
Resolution |
| QR code won’t scan |
Glare, bad angle, or dirty camera |
Reposition QR code, clean camera, try another device, reload browser |
| Let In shows error |
Invalid ticket, duplicate, or sync issue |
Verify ticket, refresh browser, re-scan, correct show is selected |
| Let In tool crashes |
Browser or mobile OS error |
Restart browser/app, update system or switch devices |
Network & Server
| Issue |
Possible Cause |
Resolution |
| Devices not syncing with server |
Wi-Fi drop or server not responding |
Check devices are on the same network, Restart router or server, check local connectivity |
| Lag / delay between users |
Network congestion |
Segment VR and guest Wi-Fi; prioritize device traffic |
Guest Experience & Flow
| Issue |
Possible Cause |
Resolution |
| Long wait times |
Scanning or onboarding bottlenecks |
Add more staff; split into multiple Let In/check-in areas |
| Guests confused during signup |
Lack of instruction or unclear signage |
Add clear instructions, signage, or video explainer loop |
| Group mismatch after signup |
Individual signups for intended group |
Reassign users into correct group manually in dashboard |
đź’ˇ Tips for Attendants
- Keep a spare mobile device ready and charged
- Have lens cloths and wipes available for quick headset cleaning
- Post a network checklist in the back for quick checks
- Provide a laminated “Quick Fix” reference sheet at each key station
- Never debug Headsets while trying to onboard users. Always send to operators for review.
- Always have fully charged backup batteries accessible
For advanced troubleshooting or persistent issues, contact your technical operator.