A searchable, symptom-based tool for diagnosing problems with an existing WLED installation.
Type what you’re actually seeing — "flickering", "wrong colour", "won’t connect" — rather than guessing at the underlying cause. The search matches against symptoms, causes, and solutions.
Use the category tabs (Power & Wiring, Wi-Fi & Connectivity, LED Signal & Effects, WLED Configuration) to browse issues grouped by the part of the system most likely responsible.
Each entry shows a one-line symptom and cause summary. Click it to expand the full step-by-step solution.
If you’re seeing multiple symptoms at once (flickering AND wrong colours AND random resets), check Power & Wiring first — an undersized power supply or voltage drop is often the root cause of several apparently unrelated symptoms.
The Troubleshooting Guide is structured by symptom rather than by component. Find the description that matches what you are experiencing and follow the diagnostic steps for that specific symptom, in order. Most WLED problems are resolved by the first or second step in the relevant section.
Before using the troubleshooting guide, confirm: your power supply voltage matches your strip's rated voltage exactly; your LED count in WLED settings matches the actual number of LEDs on your strip; and your strip type in WLED settings (WS2812B, SK6812, APA102, etc.) matches your actual strip. Three-quarters of reported WLED problems are caused by a mismatch in one of these three settings.
The WLED Discord server has a dedicated help channel where community members — including experienced builders and WLED firmware contributors — provide support. Describe your symptoms, your hardware (controller model, strip type, PSU), and what you have already tried. Including a photo of your wiring setup helps diagnose physical installation issues quickly.
This is almost always a color order mismatch in WLED's LED settings (RGB vs GRB vs BRG). Go to Config > LED Preferences and cycle through the color order options while watching a solid red test color — the correct setting will show pure red rather than green or blue.
High-brightness flicker is a classic undersized power supply or voltage drop symptom. Check that your power supply's rated current comfortably exceeds your calculated full-white draw, and if the flicker is worse at the far end of a long strip, that points to voltage drop — add a power injection point partway along the run.
Hold the reset button (or power-cycle three times quickly on most ESP32 boards) to force WLED into its fallback access point mode, connect to the "WLED-AP" network from your phone, and re-enter your WiFi credentials at the captive portal. If that fails, reflash the firmware via USB using the WLED web installer.
Often yes, especially after multiple firmware updates or manual JSON edits to presets. Config > Security & Updates > Factory Reset clears corrupted preset or config data. Back up your cfg.json and presets.json first if you've built up complex segment layouts you don't want to lose.