Troubleshooting Guide
NORTHSTARSHOW SYSTEMS
Troubleshooting Guide
Common symptoms with diagnostic steps and fixes
| Document Number | Revision | Date | Platform Version |
|---|
| NSSS-DOC-0110 | A | 2026-05-20 | 1.0 |
Cuemaster Issues
| Symptom | Cause | Fix |
|---|
| Activation overlay won't accept token | Token bound to different fingerprint or expired | Reissue token for current fingerprint; verify expiry |
| Cuemaster shows "Disconnected" | WebSocket broken, HelmOS down, or network issue | Refresh browser; ping Helm IP; check HelmOS Scheduled Task |
| "No project loaded" persists after deploy | Deploy returned non-200, or browser cache stale | Hard-refresh (Ctrl+F5); re-deploy from Compose |
| Firmware tab shows "No firmware bundled" | Active .nsss.compose lacks firmware/ folder | In Compose, File → Build Firmware, then Save, then re-deploy |
| GO buttons greyed out | Maintenance Mode is active | Turn Bridge key OFF, or press Ctrl+Shift+Alt+M |
HelmOS Issues
| Symptom | Cause | Fix |
|---|
| helmos.exe flashes and closes | Another HELM_OS.exe is running | helmos.exe detects this and prints a banner. Read the banner — close the duplicate. |
| "Not Found" at / | Old build, paths anchored to wrong dir | Re-run INSTALL_HELM_OS.exe to overwrite with current build |
| EADDRINUSE 0.0.0.0:8888 | Port in use by another app | Kill the offending app or override via HELMOS_UDP_PORT env var |
| License gate persists after activate | Token verification failed | Check /api/license/status for the failure reason |
Polaris Node Issues
| Symptom | Cause | Fix |
|---|
| Node never appears in Cuemaster | Wi-Fi not joining, SSID/password wrong | Open Serial Monitor at 115200 baud — read boot messages |
| Node shows fw_version "?" | Old firmware predates fw_version reporting | Re-export from Compose; re-flash board |
| OTA fails with timeout | Board's ArduinoOTA listener crashed or Wi-Fi flaky | Power-cycle the board; retry update |
| Input event not triggering cue | Debounce too aggressive, or pin direction wrong | Check Compose pin config; verify direction is "input" |
| Output channel fires once then stops | Action-fire without action-release; relay holds state | Use action-pulse instead, or add explicit action-release |
Firmware Compile Issues
| Symptom | Cause | Fix |
|---|
| "stdlib.h: No such file or directory" | Install path contains a space | Reinstall Compose to a no-space path (default %LOCALAPPDATA%\Programs\compose works) |
| arduino-cli not found | Bundled CLI missing or path issue | Reinstall Compose with the standard installer |
| Compile takes forever | Bundled toolchain on slow disk | Move install to local SSD |
Where to Look First
- HelmOS log: <install>/data/log/ — every event in chronological order
- Cuemaster Activity tab — last 50 events in real time
- Polaris Serial Monitor (115200) — board's own boot + Wi-Fi messages
- Browser DevTools console — WebSocket messages, fetch failures
- NSSS-DOC-0030HelmOS Server Guide
- NSSS-DOC-0040Cuemaster Operator Manual
Revision History
| Revision | Date | Description |
|---|
| A | 2026-05-20 | Initial publication |