Troubleshooting

Find what you see in the list below. Each entry says why it happens and what to do about it.

Inside Home Assistant, Tessera is the ESP Screen Manager app ("the app"), and its panel in the sidebar is called ESP Screens.

Many problems go away after an update. Update the ESP Screen Manager app first, then update each screen.

Installing and flashing

The USB port isn't in the list in New screen.

Why: the list shows the USB ports of the machine that runs Home Assistant. A cable plugged into your laptop doesn't count, and a server or virtual machine may have no USB port within reach.
Fix: plug the screen into the machine that runs Home Assistant. Still missing? Try a different cable. Many USB cables only carry power, not data.
Fallback, only when Home Assistant can't see any USB port (for example in a virtual machine): plug the screen into the computer you are using now and choose Install from this browser (Chrome or Edge) under Install via, as described in Getting started.

Installing from this browser: no port, or it won't connect.

This only applies to the fallback route, installing from the computer you are using now.

Why: only Chrome and Edge on a computer can reach USB, and only when Home Assistant is opened over https. Safari, Firefox and phones can't. Some computers also need a driver for the board's USB chip.
Fix:
1. Use Chrome or Edge on a computer, open Home Assistant over https (for example your Home Assistant Cloud address), and use a USB data cable.
2. If the computer asks for a driver, install the one for the board's USB chip. Most CYDs use a CH340.
3. Still no connection? Hold the BOOT button on the board while you choose the port, then let go.

The build fails.

Why: the first build downloads fonts and code from the internet and needs a fair amount of memory.
Fix:
1. Open the log under Firmware & USB and look for the first real error, not the last line.
2. Check that Home Assistant has internet access and free disk space.
3. On a Raspberry Pi with little memory, a first build can fail or take a long time. Close other heavy apps and try again.

The screen doesn't join Wi-Fi.

Why: the screens only use 2.4 GHz Wi-Fi, and they get the Wi-Fi name and password from ESPHome's secrets.yaml (wifi_ssid and wifi_password).
Fix:
1. Check that your network offers 2.4 GHz.
2. Check that those two lines in secrets.yaml are correct.
3. Use your main network. Guest networks often block devices from reaching Home Assistant.
4. Install the screen again.

A new feature doesn't show on the screen.

Why: most features need a newer app and newer firmware (the screen's own software).
Fix:
1. Update the ESP Screen Manager app first, then update each screen.
2. In ESP Screens, click Update next to the screen. No Update button? Go to Firmware & USB, choose the screen's profile and Wi-Fi / OTA (an update over Wi-Fi), then click Build & install.
3. Reload any ESP Screens tabs you left open during the update.

The screen restarts over and over and can't be updated over Wi-Fi.

Why: a screen that restarts too quickly never stays connected long enough to take an update.
Fix: plug it into USB and install it once from New screen or Firmware & USB. Choose the screen's existing profile, so it keeps its name and keys. After that, updates over Wi-Fi work again.

Messages on the screen

The screen stays on "Connecting to Home Assistant".

Why: Home Assistant hasn't connected to the screen yet.
Fix:
1. In Home Assistant, go to Settings → Devices & services.
2. Add the ESPHome device it found. Or add the ESPHome integration by hand, with the screen's IP address and port 6053.
3. Paste the API key when Home Assistant asks for it.
Did the screen work before? It may have a new IP address: see the first entry under Home Assistant.

The screen shows "Waiting for ESP Screens".

Why: Home Assistant is connected, but the ESP Screen Manager app hasn't sent the screen its tiles yet.
Fix: check that the ESP Screen Manager app is running, and that the screen's Tile settings entity isn't disabled in Home Assistant. A newly added screen normally shows up in ESP Screens within about 30 seconds.

The screen shows "Choose tiles in HA".

Why: everything works, but the screen has no tiles yet.
Fix: open ESP Screens, click the screen, add tiles from the Library and click Save & send.

The screen restarts over and over on "Loading tiles...".

Why: firmware 0.3.6 had a bug on screens that keep their pages in extra memory (every screen except the CYD, the Waveshare 3.5-inch and the Hosyond 4-inch). A page 1 with a clock, a graph or a wide card could make them restart during loading.
Fix: update the ESP Screen Manager app first, then update each screen. You need app 0.3.13 and screen firmware 0.3.7 or newer. If the screen restarts too fast to update over Wi-Fi, install it once over USB, as described above.

The screen shows "Preparing pages" with a counter.

Why: this is normal. After a new layout arrives, larger screens build every page once before they show them, so page changes are instant later.
Fix: nothing. Wait until the counter finishes.

The top bar says "HA not connected" or "ESP Screens not active".

Why: the screen lost its connection to Home Assistant, or hasn't heard from the ESP Screen Manager app for a while. It keeps showing its last tiles until the connection is back.
Fix: check that Home Assistant and the ESP Screen Manager app are running. After a restart of the app, the screen recovers within about a minute.

The screen shows "Configuration problem. Update add-on."

Why: the screen's firmware is newer than the ESP Screen Manager app.
Fix: update the ESP Screen Manager app. The message then goes away by itself.

The screen shows "Configuration problem. Check screen and add-on versions."

Why: the app and the screen don't understand each other's layout.
Fix: update the ESP Screen Manager app first, then update each screen.

Touch

CYD or Hosyond 4-inch: taps land in the wrong place.

Why: these screens have resistive touch, which has to be calibrated for each panel.
Fix: calibrate again.
1. Hold the top bar of the screen for about one and a half seconds to open its settings.
2. Go to This screen and tap Calibrate touch. (The same button is also in ESP Screens, on the screen's Screen settings tab, and in Home Assistant on the screen's device.)
3. Tap each crosshair three times, holding each tap for a moment. There are five positions.
4. If a measurement is rejected, the screen asks you to start again.

The other screens have capacitive touch and don't need calibration.

CYD: taps are off after you turned the screen with an Override YAML.

Why: older versions didn't calibrate a turned screen correctly, and an override that sets the rotation fights with the built-in setting.
Fix: remove the rotation from the screen's Override YAML. Choose lying down or standing up under New screen instead. Build the screen again and calibrate once.

A tap switches something twice, or it switches back.

Why: often a Home Assistant automation reacts to the same device and repeats or undoes what the tile did.
Fix: check your automations for that device. Then try the same action from Home Assistant's own dashboard, to see whether it behaves the same way there.

Picture and brightness

CYD: the picture is garbled, noisy, black, shows the wrong colours or has a bar of junk along one side.

Why: CYDs that look the same come with different display chips. Most have an ILI9341, some an ST7789V.
Fix:
1. Install the screen again with New screen and pick the other Display controller.
2. Still wrong? Open the screen's Override YAML (under More) and add one of these lines under substitutions::
  - DISPLAY_DATA_RATE: 20MHz for noise or a garbled picture
  - DISPLAY_INVERT_COLORS: "true" for inverted colours
3. Click Save & check, then update the screen.

Don't copy fixed sizes or rotations from old forum posts. They break portrait mode. Choose lying down or standing up under New screen.

Guition 4-inch: the screen looks off at any brightness below about 90 %.

Why: on many of these boards the backlight can't follow the fast dimming signal older firmware used.
Fix: update the screen. Screen firmware 0.3.5 or newer dims correctly over the whole range. If you added a backlight override from an older forum post, it still works, and you can remove it.

Waveshare 4.3-inch or 7-inch: the screen never goes dark in standby.

Why: this is on purpose. On these boards, switching the backlight back on from dark can drop the power enough to restart the board. They have no standby or night mode.
Fix: nothing to fix. The screen stays lit while it is powered.

Guition 7-inch (JC1060P470): a white screen with a band of noise.

Why: this board comes with two different panels.
Fix: look for V2 on the label on the back. Install the screen again with the other choice (JC1060P470 or JC1060P470 V2). The wrong choice does no harm.

Guition 7-inch (JC1060P470): it works after installing but won't start after a power cut.

Why: older firmware started the panel too quickly after a cold start.
Fix: install it once over USB with screen firmware 0.3.4 or newer.

An experimental board shows only the page buttons and no tiles.

Why: the tiles never reached the screen, often because the app and the firmware are out of step.
Fix: update the ESP Screen Manager app first, then update each screen. Put a few tiles on the screen and click Save & send. If it stays blank, open an issue with a photo of the screen, both version numbers and a log from boot. Remove Wi-Fi passwords and keys from the log first.

Home Assistant

The screen was working, but after a power cut or a USB replug it stays on "Connecting to Home Assistant".

Why: your router may have given the screen a new IP address. Home Assistant can keep trying the old address for a while, especially after the screen lost power without a clean shutdown.
Fix:
1. Hold the top bar of the screen for about one and a half seconds to open its settings. Go to This screen and note the Address.
2. Tap Restart on the same page. After a clean restart, Home Assistant usually finds the new address by itself within a minute or two.
3. Still unavailable? In Home Assistant, go to Settings → Devices & services → ESPHome, open the menu of the screen's entry and choose Reconfigure. Enter the new address.
To prevent it: give the screen a fixed address in your router. Routers often call this a "DHCP reservation".

Home Assistant doesn't find the screen.

Why: discovery didn't reach Home Assistant, or the network keeps devices apart.
Fix: add the ESPHome integration by hand with the screen's IP address and port 6053. Guest networks and some mesh systems block devices from talking to each other, so use your main network.

Home Assistant asks for a key, or Copy API key copies nothing.

Why: browsers block copying when Home Assistant is opened over plain http://.
Fix:
- When copying is blocked, ESP Screens shows the key selected in a box. Copy it with Ctrl+C, or Command+C on a Mac.
- For a new screen, click Show the API key in ESP Screens. For a screen that is already added, open it in ESP Screens and use Copy API key.
- The key is also in the screen's YAML, under api:, encryption:, key:.
- Don't use the OTA password (the password for updates over Wi-Fi). It is a different key.

Tiles show values, but tapping does nothing.

Why: Home Assistant doesn't allow the screen to control your devices yet.
Fix:
1. In Home Assistant, open Settings → Devices & services → ESPHome and find the screen.
2. Click Configure.
3. Turn on Allow the device to perform Home Assistant actions.

A tile says it is unavailable.

Why: the entity it shows is missing or unavailable in Home Assistant. A renamed entity counts as missing.
Fix: check the entity in Home Assistant. If you renamed it, choose it again for that tile in ESP Screens.

A vacuum or thermostat tile offers fewer options than you expect.

Why: each integration supports different modes and settings, and the tile only offers what Home Assistant reports.
Fix: try the same action in Home Assistant itself. If it isn't there either, the integration doesn't support it.

Tiles aren't on the page you expect, or you can't reach a page.

Why: every tile keeps the cell you gave it. How many tiles fit on a page depends on the screen, and a screen has at most eight pages.
Fix: in ESP Screens, drag tiles to the cell you want and click Save & send. No update of the screen is needed. If you turned Page buttons off, only swiping and Go to page tiles change the page. The editor warns you when nothing leads to a page.

Docker

The ESP Screens container shows "unhealthy".

Why: very old versions used a health check that could never pass.
Fix: update the app. It brings its own health check.

The ESP Screens panel shows "502: Bad Gateway".

Why: Home Assistant runs on Docker's bridge network, so it can't reach the app on 127.0.0.1. This is common with Docker Desktop on Windows and macOS.
Fix: let the app share the Home Assistant container's network, as described in Home Assistant on a bridge network.

Still stuck?

Open an issue on GitHub and include:

the board you have, and which version you picked in New screen
the ESP Screen Manager app version and the screen's firmware version (on the screen: This screen → Firmware)
a photo of the screen
the device log from boot until the problem shows, with Wi-Fi passwords and keys removed

For measuring a CYD's touch over USB, see the calibration guide.