Skip to main content
← Back to Documentation

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:

Check Universe Output

In QLC+ web UI, go to Inputs/Outputs and ensure universe output is enabled

Verify ENTTEC Selection

Confirm ENTTEC is selected as the output plugin for the correct universe

Check DMX Addresses

Verify fixture DMX addresses in QLC+ match their physical DIP switch settings

Test DMX Output
./lightsctl.sh test-dmx

Still Having Issues?

Join our community for help from other users and developers

Join DiscordReport Issue