Troubleshooting your light show with xLights

Welcome to troubleshooting for beginners (veterans welcome)

So you gathered everything you need to start your xLights light show, you install all your PVC and j-channel, put your props in your yard, you plug in your lights and fire up xLights, start your sequence and boom.... welcome to troubleshooting a light show. 

Some of you may of course plug in everything and fire up xLights and in fact, everything works as expected. I can tell you that for most people, this isn't going to be the case. And I can also tell you there is a high probability that those results, won't last season over season.

Here is a list of the most common problem that people face in this hobby. (NOTE: This troubleshooting guide is designed with the expectation that you already setup and configured your show.) Please see my guide below on starting a light show first if you don't have a baseline understanding of the process. 


Question and Answer(s)


Q1. My lights don't light up when playing a sequence.

A1. Check power: Verify power is on for all devices involved in making your show function. All power supplies, network devices, show players and controllers.

A1. Check functionality: Most controllers are accessible through a web browser. Login to your controller and make sure it is accessible. Not only does this verify the controller has power, but it also verifies you have connectivity through your network device(s) which is vital for communication to and from your show player. If you cannot connect to your controller, you either have a controller with no power, your network device is not working properly, your cable is not working/connected or, your computer isn't talking to your show network properly / you have a network configuration problem. There is an off chance that your controller network port has also failed but this is rare. 

A1. Verify data output: For testing data output, the feature used for this is most commonly an option in the controller setup page. That option is called "test mode". When you put the lights in "test mode", you are sending a signal from your controller direct to the lights. This verifies your controller can send signal(s) to the lights. If after sending a test signal, certain lights are not lighting up, you either have a configuration problem or, you have a hardware / wiring / pixel or node problem. We will cover these problems in more detail later.

Return to Top

Q2. Some of my lights aren't working or are flickering.

A2. If your lights don't light up at all while playing a sequence, and you are sure they worked before using them, first put your controller in test mode. If they light up in test mode, you have a configuration problem in your controller or in xLights. Usually this means you have not told the controller the proper amount of lights in your strand or setup. Or, you did not tell the controller where (what port or plugin) to find that set of lights you want it to communicate with. To diagnose this, open xLights and open your controllers configuration page. In the setup page, make sure your pixel/node counts (total amount of pixels/nodes) are what you expect them to be and that the location/port you told the controller your pixels/nodes were connected to, is in fact the port where you plugged in your lights on your controller or receiver board.

A2. If your lights are flickering, there are a few possible causes.

1. The lights are not getting enough power delivered to them. (NOTE: this and water issues are the most common cause for flickering lights when first setting up.) You can check if you are not getting enough power by using a voltmeter to check the voltage at the end of the strand of pixels/nodes. If your voltage is less than 10 volts coming out of the end of the lights, you are likely not giving the pixels enough power to work properly. Lack of power creates all kinds or erratic behavior but mostly it causes flickering, flashing, or no light being emitted. 
2. You have a data delivery problem. Data, like power, also has a limitation in regards to how far you can run your cords or strands without boosting the signal. To test whether or not this can resolve your problem, you will need to purchase an F-Amp signal amplifier. Vendors may have different names for this device but it is basically just an inline signal amplifier. The amplifier helps push the signal further down the strand to resolve long distance problems. 
3. You have water in a connector. Water getting into your "waterproof" connectors is a common problem. Although we should be able to trust a waterproof connector is in fact waterproof, they don't always work as expected. The only way to check for this is to pull apart a connector and check for water. This will most commonly make your lights go crazy meaning the colors will be all over the place and lights will go on and off in wild patterns. Pixel/node failure can also mimic this behavior so again pulling apart the connector to check for moisture is the best way to identify water related problems. 
4. You have a dead pixel in your display. When a pixel or node goes bad, it stops transmitting data downstream. To resolve this, you will need to cut the bad pixel out and replace it with a good known working pixel/node. 


Return to Top

Q3. After making a repair, my repaired section does not work in test mode.

A3. Wired not spliced properly: When you splice a wire running to a node/pixel, you need to make sure that the wires are in proper order. The positive, data and negative leads needs to be lined up exactly as your existing strands. Also, you have to make sure the direction the data flows in also in alignment. 

A3. Dead pixel causing disruption: If you have a dead pixel just before your repair, your repair will not light up. NOTE: data has to flow from the controller through the pixels on a one way only road. Dead pixels act as a road block stopping all traffic past the dead pixels. 


Return to Top

Q4. My power supply isn't working.

A4. Troubleshooting power supply failures is limited because their function is simple. The most common cause for a power supply failure is a fault in your wiring connected to the power supply. Sometimes, that can be caused by animals chewing cords, water exposure to power cord connectors, positive leads shorting out due to wiring problems or exposed ends. Once you correct the faulty wiring, most high quality power supplies (Meanwell) simply reset back to working order. To troubleshoot, disconnect all items wired into the power supply and reset the power supply by removing and adding power. If the power supply does not come back to life, there is likely a problem with the power supply that you cannot repair.

Return to Top

Q5. Lights on my prop are going the wrong direction when playing my sequence in xLights.

A5. The root cause to this is relatively simple. The prop is either hung on the house or stand, at an angle, upside down or, the wiring was done in reverse. The great news is, you can rotate the prop physically to correct angle related concerns and, you can virtually flip the prop in xLights to make a full horizontal or vertical flips.


Return to Top

Q6. Playing an xLights sequence on my house look nothing like expected.

A6. There are a few common causes for unexpected results being displayed on your home. The first is, that you made a change to your layout in the xLights software and did not render your sequence and save it. The second is that you did not upload the most recent version of your layout to your controller. If the controller does not know about your changes, and you added more or less lights to your display, the controller will still send signal out to the lights it thinks are there. To resolve this problem do the following

1. Open your sequence in xLights.
2. Render your sequence and save it. 
3. If xLights was already open, make sure to save your layout.
4. Make sure you place your saved sequence in your show folder.
5. Upload your layout to your controller.
6. Test again.

Return to Top

Q7. My original layout worked fine but after adding new props or stands the new layout doesn't look right

A7. When you update your layout, you have to pass that new information to your controller. If you don't, your controller will get the information from the sequence regarding where to send what effects and send it to what lights you had in your original layout. Remember, all lights are individually addressed by the controller. This of course happens automatically through the xLights software but be mindful that there is a very specific order by which your lights are fed data. If you told the controller you have 1000 lights, it labels each light 1 then 2 then 3 etc.. through to 1000. If you add more lights to your layout, and usually you add those lights somewhere in the middle, anything past the changed area will have the wrong addressable number. Basically, the instructions for each light get shifted and since we work with an absolute pixel to pixel ordered definition, your sequential order will be greatly disrupted. All that is needed to correct this is to simply upload the proper configuration data to the controller from xLights.  

Return to Top

Q8. My FM transmitter produces a fuzzy signal

A8. You have placed the transmitter in a location that does not allow your signal through. To resolve the problem, simply move the transmitter to a new location away from all obstacles.

A8. The placed height of the transmitter is too low. Moving your transmitter to the highest point possible in your home can help with range and quality.

A8. Your antenna is insufficient for the distance you are trying to transmit your signal. Antennas can be replaced with larger alternatives. Careful consideration needs to be made to ensure the antenna is appropriately sized for your transmission signal. Make sure before doing anything you understand how transmitters work and, that you follow any laws involved regarding the limitations surrounding transmission of short range FM signals. 

Return to Top

Q9. Color output problems (RGB, BRG, RBG)

A9. You have told xLights that the order your color LED's are in, is incorrect. This could make blue look red and red look green etc.. Most pixels/node are set in RGB (red, green, blue) order. Some strips will be set differently and other LED lights in different formats, may be different as well. It is very important to know the order your LED's inside your pixel/node are in.

A9. Your controller has the wrong color order set inside of it. If you manually manipulate information inside of the controller to setup your layout, you may have set the color order incorrectly. Verify your LED color order is correct inside your controller layout. It is best to let xLights deal with color order where possible.
A9. The manufacturer made defective LED's strands. Unfortunately the chips inside of your LED's can be defective leading to the color curves used to produce colors to be wrong. This can commonly happen when purchasing low quality LED's from China. To avoid this, purchase LED's in the group buys or from known reputable sellers. The vendors in the group buy make most of their living from us. They do not want to upset us because they know it could have a large impact on their income. This forces better quality components and testing at their factories. 

Return to Top

Q10. Troubleshooting a long range receiver board in chain order (i.e. A,B,C). (NOTE: this is for controllers that use long range receivers only.)

A10. Receiver boards, especially those linked together, require specific instruction in xLights and physical instructions on the receiver board to work properly. If you are facing trouble with a receiver not lighting up pixels/nodes do as follows.

1. Verify your are getting signal from the controller. If you are receiving signal from the controller, the colored LED lights on the receiver board will light up. If the lights are not lighting up, the network cable/Ethernet cable is likely not working properly. Verify the cable is in good condition and that the ends are secure. If everything looks in good working order, you can use an Ethernet cable tester to confirm the cable is sending signal through each wire in the cable. Very affordable testers are available on Amazon. If the tester confirms the wire is good, your receiver is either not setup in your configuration in xLights or, your receiver board is not functioning properly.
2. Use the test function of the receiver board. If the test function does not work, you either have fuses that are blown, the power supply is bad or the receiver board is bad. Check and or replace each piece of hardware until your issue is resolved.
3. If your receiver board is the last in a series of boards, you need to make sure termination of the data signal is set. On Falcon products, you need to move DIP switches (little white switches on the board) to the on position indicating this is the last point/receiver in the chain.
4. Verify you have set the letter value (A,B,C etc..) chain order on the receiver board and in xLights, to the same value. Receiver boards must follow the alphabet in order. You can't put "A" then "C" then "B". Verify you have the correct order set on the receiver and in xLights.  


Return to Top

Q11. I am having networking / communication problems between devices. (NOTE: Wi-Fi or wireless connectivity opens up a wide variety of environmental problems. Where possible, wire direct connections to your controllers or receivers to avoid having to troubleshoot wireless problems.) 

A11. The most common cause for communication problems where wiring is used is Ethernet cables. If you are having issues with a device either not being seen in software or not receiving information, check your Ethernet cable. The best way to test and check is to replace the cable. Before doing that you need to check and inspect the ends of the cable to make sure they are seated properly in the device you plug them in to. For relatively low cost, you can purchase an Ethernet cable tester on Amazon. Any tester will work. Alternatively, you can place the cable in between two known working devices and confirm the cable works for those two devices. 

A11. Wireless connection problems are almost always about range or interference. If you exceed the range of your wireless routing device, you will have issues communicating from your controller to your wireless device. Range and interference will vary greatly based on placement of your wireless router, quality of your wireless router, amount of walls you are transmitting through, interference in your homes wiring, or interference outside of your home. There is no great way to identify or repair interference problems except by making sure your power going to the router is clean. You can do this by adding in a battery backup or line power conditioning device. There are no guarantees either of these devices will make a difference. They are simply a step you can take to try and troubleshoot. The best alternative in my opinion is purchasing a router or series of routers to increase your overall coverage of your wireless network. Personally, I would confirm all wireless devices work in short range close to the wireless router before bringing them outside. Also, make sure to power off and on all devices once configured to make sure they all work after losing power. If your device is not saving configuration data, reach out to the manufacturer to determine why those settings are not being saved.  

 Return to Top

Back to blog