Troubleshooting

Troubleshooting

Common issues and how to fix them.

Quick Diagnostics

Start with these commands to identify issues:

./lightsctl.sh doctor      # Full health check
./lightsctl.sh validate    # Pre-flight validation
./lightsctl.sh diagnose    # Detailed diagnostic dump

From an MCP Agent

If you've installed the MCP server (mcp-install), three diagnostic tools are available to any connected LLM client:

Tool	What it checks
test_dmx	Runs a known-good R → G → B sweep across every fixture's color channels and restores prior state. Visible confirmation that DMX is reaching the rig.
get_logs(service, n?)	Tails the systemd journal for qlcplus-web, lighting-control, lighting-mcp, or nginx.
get_system_info()	Pi-level health: CPU temperature, load, memory, disk, uptime, USB devices, service status.

Tell your agent "the lights aren't responding, what's wrong?" — it can call all three in sequence to triage without SSHing in.

ENTTEC Not Detected

Symptoms:

• test-dmx command fails
• No DMX output from fixtures
• USB device not showing in lsusb

Solutions:

Verify USB Connection

./lightsctl.sh test-dmx
./lightsctl.sh lsusb

Check User Permissions

./lightsctl.sh ssh
groups $USER   # should include dialout

Replug Device

Unplug and replug the ENTTEC. If harden was run, it should appear at /dev/dmx0.

---

QLC+ Service Won't Start

Symptoms:

• Web UI not accessible
• Service status shows failed
• Logs show Qt platform errors

Solutions:

Check Service Logs

./lightsctl.sh logs
./lightsctl.sh logs-errors

Fix Qt Platform Issues

./lightsctl.sh qlc-headless
./lightsctl.sh restart

Verify Installation

./lightsctl.sh doctor
./lightsctl.sh health

---

Can't Find Pi on Network

Symptoms:

• lights.local doesn't resolve
• SSH connection fails
• Can't access web UI

Solutions:

Scan Network

./lightsctl.sh scan
./lightsctl.sh check

Check WiFi Configuration

Ensure WiFi credentials were set correctly during SD card preparation.

Try Direct IP

Check your router's DHCP leases to find the Pi's IP address, then update PI_HOST in .env.

---

Web UI Hangs or Doesn't Load

Symptoms:

• Browser connects but page never loads
• Spinning wheel forever
• Interface unresponsive

Solutions:

Remove --operate Flag

./lightsctl.sh ssh
sudo sed -i 's/--operate//' /etc/systemd/system/qlcplus-web.service
sudo systemctl daemon-reload
sudo systemctl restart qlcplus-web

Restart Service

./lightsctl.sh restart
./lightsctl.sh health

---

Lights Not Responding

Symptoms:

• DMX fixtures don't respond
• Scenes don't affect lights
• Everything else works

Solutions:

1. Check Universe Output — In QLC+ web UI, go to Inputs/Outputs and ensure universe output is enabled
2. Verify ENTTEC Selection — Confirm ENTTEC is selected as the output plugin for the correct universe
3. Check DMX Addresses — Verify fixture DMX addresses in QLC+ match their physical DIP switch settings
4. Test DMX Output:

./lightsctl.sh test-dmx

---

Still Having Issues?

• Report an issue on GitHub
• Join the community on Discord