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

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