First: is it power or is it data?
Before you change any setting, work out which side the fault is on. It takes ten seconds and it saves you from adjusting software settings for a problem that is actually a loose wire.
| What you see | Where the fault is |
|---|---|
| Gradual fade towards one end, white looks yellow | Power — voltage drop |
| Dimming or flicker only during bright frames | Power — supply undersized |
| Wrong colours across the whole strip | Data — signal order |
| Effect moves in the wrong direction | Data — layout |
| Random flicker at any brightness | Data — ground or cable |
| Strip dead from one point onwards | Data — failed pixel |
If the answer is power, stop here and read the wiring and power injection guide — no software setting will fix it. If the answer is data, carry on down this page.
Colours are wrong
Symptom: the movement of the effect is correct, but red comes out green, or blue comes out red. The whole strip is affected equally.
Cause: the RGB signal order in the hardware setup does not match what the strip expects. The controller sends three colour values per pixel, and different strips expect them in different sequences. Many WS2812B strips want green first, so a strip set to RGB will show red and green swapped.
Fix: open the hardware setup screen and change the signal order. Work through the options in turn — RGB, GRB and BRG cover the great majority of strips. Test with a plain red frame: when red shows as red, you have found it.
White looks the same in every signal order, so it tells you nothing. A single solid red frame identifies the correct order immediately.
Effect runs backwards or breaks at each row
Symptom: a chase that should sweep left to right runs right to left, or a wave jumps back to the start on every second row of a matrix.
Cause: the pixel layout drawn in the software does not match how the strip is physically wired. The software has no way of knowing your wiring; you have to tell it.
Fix: redraw the layout so it follows the real path of the strip. If the fixture goes left to right on one row and then right to left on the row below — a serpentine or zig-zag layout — draw it that way. If it returns to the left edge before starting each row, draw that instead. The two are not interchangeable and using the wrong one is the single most common cause of broken-looking matrix effects.
Effect only fills part of the strip
Symptom: the effect plays correctly but stops a third of the way along, or it races through and repeats before reaching the end.
Cause: the pixel count in the software does not match the real number of addressable pixels.
Fix: count your addressable pixels, not your LEDs. On a 12V WS2811 strip, three physical LEDs usually make up one pixel — so a strip with 300 visible LEDs may only be 100 pixels. Enter 300 and the effect will only fill the first third. Our WS2811 vs WS2812B guide explains how to tell which you have.
The reliable test: program a chase that lights one pixel at a time. Watch whether one LED moves or three move together, and count what actually travels.
Random flickering
Symptom: pixels flash or change colour on their own, at unpredictable moments. It may work fine on the bench and misbehave at the venue.
This one has several possible causes. Check them in this order:
Common ground
If the controller and the strip run from different power supplies, their negative terminals must be joined by a wire. Without it the strip cannot read the data reliably. This is the most frequent cause of flickering that appears only on site.
Length of the data cable
A long run from the controller to the first pixel degrades the signal. Move the controller closer, or use a shielded or twisted-pair cable for the run.
Power supply capacity
If the flicker only appears on bright frames, the supply is sagging under load. Size up or add power injection.
IC type setting
An IC type that does not match the strip produces timing errors that look exactly like flicker. Confirm the setting matches the strip in front of you, not the one you used last week.
Strip works up to a point, then nothing
Symptom: the first section lights and behaves perfectly. From one particular pixel onwards, nothing.
Cause: a failed pixel. Each pixel receives the data and passes it on to the next, so a dead one breaks the chain and everything after it goes dark.
Fix: find the last pixel that lights correctly. The fault is the one immediately after it. Replace that single pixel or cut it out and bridge the connection. The rest of the strip is fine.
A short piece of the same strip and three lengths of wire lets you bypass a dead pixel in a few minutes on site. Far quicker than replacing a whole fixture during an event.
Nothing lights at all
Work down this list in order. The fault is nearly always in the first three.
- Data direction. Every strip has a printed arrow showing which way data flows. Connected backwards, you get nothing at all — no partial result. This is the number one cause.
- Power reaching the strip. Meter the strip's power pads. If there is no voltage there, the problem is upstream and has nothing to do with data.
- Ground connection. Data with no shared ground does nothing.
- Controller has a valid file. Check the SD card was written and that the controller shows it is playing.
- Correct port. On a multi-port controller, confirm the strip is on the port you configured in software.
Controller will not read the SD card
Symptom: the card is written without any error message, but the controller does not play anything, or shows a card error.
Four things to check, in order of how often they turn out to be the problem:
- Card size. Cards larger than 32 GB are the most frequent cause. Use 32 GB or smaller.
- Format. The card must be FAT32. A card formatted exFAT or NTFS will be rejected. Reformat, do not just delete the files.
- File location. The exported files must sit in the root of the card, not inside a folder.
- Card quality. Very cheap or counterfeit cards fail unpredictably. Keep one known-good card as your reference for testing.
Our SD card export guide covers the whole write process in detail.
Software will not open
Symptom: nothing happens when you launch it, or it closes immediately, particularly on Windows 10 and 11.
Try these in order:
- Compatibility mode. Right-click the executable, open Properties, go to the Compatibility tab and set it to run in Windows 7 mode. This resolves the majority of cases.
- Run as administrator. The software writes configuration files and may be blocked without elevated permission.
- Install path. Extract to a simple folder on the C: drive. Long paths, spaces and non-English characters in the folder name cause problems with older software.
- Run from the extracted folder. Running the installer from inside a ZIP archive without extracting it first causes missing-file errors.
Do not switch off your antivirus to force an installation. Scan the file, and if your security software reports a genuine problem, obtain the software from a different, trusted source instead. A blocked install is never worth the risk of running something unknown on the machine that holds your project files.
Questions we get asked
The effect looks perfect in preview but wrong on the fixture. Why?
Two candidates: the pixel layout does not match the physical wiring, or the signal order is wrong. Check the layout first, since it explains both direction and pattern faults.
It worked in my workshop and failed at the venue. What changed?
Usually the power arrangement. In the workshop everything runs from one supply; at the venue the controller is often on a different feed, which removes the shared ground. Add a ground wire between the two supplies.
Half my matrix shows the correct image and half is scrambled.
Serpentine layout drawn as linear, or the reverse. Redraw the layout to match how the rows are actually joined.
My colours changed after I swapped in a strip from a different reel.
Different batches sometimes use a different signal order even when the label is identical. Re-check the RGB order for the new strip rather than assuming it matches the old one.
Do I need to re-export after changing a hardware setting?
Yes. The exported file contains data built from the pixel count, layout and IC settings. Change any of those and the old file no longer matches — write a fresh one.
Send us the symptom, your controller model, IC type and pixel count through the contact page. If it is a fault others are likely to meet, we will add it here.
Rajkumar
Six years in the pixel LED industry, running a manufacturing and supply business for event decorators and tent professionals across India, and teaching controller programming to working technicians on YouTube.