Troubleshooting common issues

Black screen / no UI after boot

1. SSH in and check PM2: pm2 status — is m2c2 online?
2. Hit the app URL from the Pi: curl -I http://127.0.0.1:3000 (port may differ).
3. Chromium autostart — verify ~/.config/autostart/*.desktop points to the correct URL.
4. HDMI — add hdmi_force_hotplug=1 in /boot/firmware/config.txt if the TV sleeps the input.

PM2 process keeps restarting

1. pm2 logs m2c2 --lines 100 for stack traces.
2. Out of memory — close extra tabs; prefer 8 GB Pi; reduce heavy modules.
3. Native module rebuild — npm rebuild after Node upgrades.

Voice / Hey Piper not responding

1. Confirm mic in alsamixer / PulseAudio is unmuted.
2. Re-run wizard mic test or calibrate sensitivity in Settings → Voice.
3. Check CPU load — STT can starve on overloaded Pis.

Google Calendar empty or errors

1. Re-authorise under Settings → Integrations → Google.
2. Confirm the calendar ID and that events are on the selected calendar.
3. Verify system time (NTP) — OAuth and token refresh break with wrong clocks.

Smart home devices offline

1. Hue bridge — same subnet, bridge IP static, no guest Wi‑Fi isolation.
2. Tuya — cloud credentials / local key rotation per Tuya’s app policy.
3. Home Assistant — long-lived token still valid, URL reachable from Pi.

Networking / slow UI

1. Prefer Ethernet for a wall-mounted mirror.
2. DNS — try router DNS or 1.1.1.1 if lookups hang.
3. SD card — replace worn cards; check dmesg for I/O errors.

Still stuck?

1. Open an issue with logs (pm2 logs), OS version (cat /etc/os-release), and hardware (Pi model, PSU).
2. See Community for where to report.