Troubleshooting

A symptom, its usual cause, and where the fix is.

Most problems fall into one of four places: the board does not show the screen, the screen is wrong, the build does not compile, or the designer is telling you something. Each has a short list of usual causes.

On the board

Symptom	Usual cause
Nothing on serial	Wrong COM port or baud (it is 115200); a charge-only cable; USB CDC On Boot not enabled on an S3 or C3 with native USB.
White or black screen, `UI ready` printed	Backlight pin or its active level is wrong; or the panel is not initialised - wrong controller, bus or library driver on the Display tab.
White screen, nothing printed after the name	The panel init is hanging: SPI pins wrong, or a reset line not wired.
`draw buffer allocation failed`	Lower Buffer height in the export settings. On an S3 with PSRAM, enable it in the IDE and tick Buffer in PSRAM.
Reboot loop as the UI starts	The same memory problem; or PSRAM enabled in the project but not in the IDE; or an RGB panel without PSRAM.
Colours inverted	Toggle Invert on the Display tab.
Red and blue swapped	Switch the colour order between RGB and BGR.
Mirrored or rotated image	Change Rotation, then fix the touch axes if they no longer match.
Touch does nothing	Wrong I2C address; the controller shares a bus that is not marked as shared; its reset line not wired (CST816S); INT pin wrong. The serial output says whether it answered.
Touch offset or mirrored	Swap X/Y, Invert X, Invert Y on the Touch tab; resistive controllers also need Calibration.
Touch works on part of the screen	Resistive calibration values, or the touch resolution does not match the display rotation.
Random pixels, tearing, flicker	SPI clock too high for the panel or the wiring - lower it; shorten wires. RGB: PSRAM speed, pixel clock.
Images are empty boxes	The filesystem was not uploaded (`pio run -t uploadfs` or the IDE plugin); or the wrong filesystem type; or the partition scheme has no room. `ui_fs_init()` names each missing file on serial.
A sensor never changes	Reported absent at boot: address, bus, pull-ups, power. The Devices tab address must match the part's strapping.
A readout lags or jumps	The device's poll interval is long, or an analog input's smoothing is high. Both are on the Hardware tab.
A slider snaps back when touched	Its binding is Variable → widget only. Set the Direction to Both ways.
Text shows `?` boxes	A character outside Montserrat's built-in range (it covers Latin, not CJK), or a font size not enabled - re-export after changing the font.

Building

Error	Fix
`lv_conf.h: No such file`, or LVGL uses default settings	Arduino IDE: `lv_conf.h` must be in `libraries/` next to the `lvgl` folder. PlatformIO: keep the generated `-DLV_CONF_INCLUDE_SIMPLE -I .` build flags.
`lv_image_create` / `lv_img_create` undeclared, or hundreds of LVGL errors	The installed LVGL major version does not match the project. Install 9.x or 8.3.x to match the export settings, or change the version and re-export.
TFT_eSPI builds but the panel is wrong	The generated `User_Setup.h` was not copied over the library's own. PlatformIO does not need it - the defines are in `platformio.ini`.
`fatal error: Adafruit_BME280.h` (or any library header)	Install it from `LIBRARIES.md`. The search string is quoted there exactly.
Sketch too big	Choose the Huge APP partition scheme, or one with a larger app partition.
`lv_colorwheel_create` undeclared on LVGL 9	The colorwheel was removed from LVGL 9 core. Enable it in `lv_conf.h` extras or target 8.3.x.
ESP32-P4 board not found	The P4 needs a recent Espressif core; update it in the Boards Manager or the PlatformIO platform.

The designer's own messages

The Check tab, the Errors tab and the export dialog show the same list. Errors block export; warnings do not. The messages name the widget, pin or variable concerned. The ones people ask about:

Message	Meaning
GPIO n (...): Strapping pin - affects boot mode	A warning, not an error. The pin is used at reset to pick the boot mode. Fine for data lines, risky for RST and backlight because a level held at boot can stop the board booting.
GPIO n (...) is input-only and cannot drive this signal	GPIO 34-39 on the ESP32 (and 46 on the S2) cannot be outputs. Move CS, DC, RST or the backlight to another pin.
GPIO n is assigned twice	Two unrelated signals on one pin. If they are meant to share a bus, mark the touch controller as sharing the display bus, or put both devices on the same named bus.
RGB panels need PSRAM for the framebuffer	Enable PSRAM on the Board tab (and in the IDE), or choose an MCU that has it.
The draw buffer (n KB) is large for ...	Lower Buffer height in the export settings.
"X" on "Screen" extends outside the screen	Part of the widget is past the edge and will be cut off. Move or shrink it.
"X" has a chart binding but no series to push onto	Add a series under Chart data, then pick it in the binding.
"X" is a scatter chart, so its points need an X value	Set X from on the chart, or change the type to Line.
"clock" looks like a clock, and "X" plots it as Y	You have bound the time variable as a value; it belongs in X from.
"X" wants a reading every n ms to cover its window	The time span divided by the point count is faster than the refresh loop. Lengthen the window or reduce the points.
Address 0x.. is used by both "A" and "B"	Two I2C devices with one address on one bus. Change one's address strap, or put it on another bus.
Analog input "X" uses prev() or delta()	Those only work in variable formulas, which run after the inputs are read.
"X" has transparency but is set to RGB565	The alpha channel will be discarded. Use RGB565A8 or ARGB8888.
Image assets total n KB, more than the roughly 896 KB available	Over the filesystem partition. Shrink or reformat images, compile some in as C arrays, or use an SD card.

The Errors tab on a project with a few warnings and one error. Clicking an entry selects the widget it names.

Accounts and quota

"Confirm your email address before generating code." The confirmation link went to the address you registered with; Resend the link sends another. Check spam.
The dialog says the allowance is used up. Without an account the guest allowance is five generations for life, counted against your connection, and creating a free account moves you to fifteen a month. On an account the period is a rolling thirty days from the first generation of the period. Accounts and limits.
Somebody else on my network has used the guest allowance. Yes - it is counted per address, so an office or a campus shares one. Registering is the fix, and is free.
"Your plan is at its project limit." The free plan stores five projects on the server. Delete one, or save over an existing one rather than as new. Projects in the browser and in downloaded .json files do not count.
Adding a screen opens a sign-in or upgrade prompt. A project is capped at three screens without an account, five on the free plan and thirty on Pro. The same cap is checked when a project is saved or generated, so opening a larger file does not get round it - the build is refused with the plan named, and nothing is charged.

The gallery

"Save this design to your account before publishing it." Publishing takes a copy of a saved project; save first.
"Published, but the preview could not be rendered." The listing exists without its picture. Usually a screen with an unusual size or an asset the renderer could not read; re-publish with Push current version after checking the Errors tab.
My published design is out of date. Publishing is a copy, deliberately. Open the publish dialog and Push current version.

Still stuck

Email admin@lcdwizard.online with the board, the serial output from boot, and - if you can - the project .json from File > Download project file. That file is the whole design and is the fastest way to reproduce what you are seeing.