Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Empty / junk STT | STT down, wrong engine, short utterance | Check Ada /health or comstar-stt; /tmp/comstar-last-utterance.wav; raise finalize threshold |
| Fast speech cut early | VAD silence too aggressive | Raise COMSTAR_VAD_SILENCE_MS (e.g. 1200) |
| Empty STT on Mac |
COMSTAR_STT_URL unset or STT down |
make stt-dev, export URL |
| Desktop flashes on boot | Session chrome not installed |
make pi-session / install-pi-session.sh + reboot |
| Rainbow / stock splash | Plymouth not installed |
make plymouth / sudo install-plymouth-comstar.sh + reboot |
| Kiosk blank / no WS | Chromium not loading kiosk after splash | Confirm bridge :8776 + splash :8769; restart comstar-kiosk
|
| Kiosk silent | Bridge down or wrong bridge= URL |
Check WS :8777
|
| Chrome has no camera preview | Expected — no webcam tile | Confirm bridge ffmpeg / LED; COMSTAR_CAMERA_SOURCE
|
| No greet-by-name | Face not enrolled |
enroll_face.sh from terminal camera |
| Recognition inconsistent | Enrollment-condition mismatch | Re-enroll under real lighting/distance; raise recognize_votes
|
| Inference latency climbs | CPAI queue contention with house cams | Drop ambient_fps; check dashboard CUDA |
| Face slow, detect fast | Face module fell back to CPU | Fix CUDA in CPAI dashboard |
| Wake fires at the TV | Threshold / negatives | Retrain with TV as negatives; raise threshold |
| Wake misses across room | Microphone, not model | Upgrade to beamforming array — Hardware |
| Avatar stutters on Pi | Heavy render | Drop resolution / keep 2D SVG; measure fps before streaming |
| Lip-sync drifts | TTS timing | Prefer shared HTMLAudio clock (ADR 0001) |
| STT hallucinates | Engine / VAD | Check Reach vs fallback; score with bridge fixtures |
| AO timeout / overlay missing | Server unreachable, relative overlay path, or mTLS not paired | Check https://…:8765; enroll AO pairing; run from repo root |
| Admin QR missing offline | No uplink and hotspot disabled | Unset COMSTAR_HOTSPOT=0; join SoftAP SSID then scan |
| Google tools missing | Not paired / guest / soft-skip | Say “connect my Google”; check env + tokens |
| Pairing QR never shows | Kiosk outdated / message dropped | Redeploy kiosk; log google_pairing_start
|
| Span numbers nonsense | NTP drift |
make doctor clock-skew check |
| Road VPN red at home | Expected until UI showed at-home | Gray At home means VPN idle by design |
make doctorMost "the bridge is broken" sessions are a CPAI module on CPU or clock skew.
