Troubleshooting

The artwork isn't loading

Album art is loaded from your Home Assistant instance. If it isn't appearing:

Check the media player entity — make sure the entity you configured on the device page has an entity_picture attribute when playing. You can verify this in Developer Tools → States in Home Assistant.
Check the Home Assistant host and protocol — the device fetches artwork from <ha_protocol>://<ha_host>:<ha_port>/api/.... If your Home Assistant instance uses HTTPS, a different hostname/IP, or a non-standard port, artwork will fail to load. Set the ha_protocol (http or https), ha_host, and/or ha_port substitutions to match your setup. If using HTTPS with a self-signed or local CA certificate, also set ha_verify_ssl: "false". See Host/Port Setup.
Check network connectivity — the device needs to reach your Home Assistant instance over the local network. Make sure both are on the same network/VLAN.
Check the image format and size — artwork is decoded on the device. Baseline JPEG, progressive JPEG, and PNG are handled by the native firmware decoder. Apple Music artwork is requested as a capped JPEG when the device can identify the public Apple CDN URL. HEIC/HEIF is detected but is not displayed by the current native firmware decoder. Very large images can also fail on the ESP32's limited memory. When reporting this, include the media provider and the device logs.
Restart the device — occasionally the image download can get stuck. A restart (via the physical button or from the ESPHome dashboard) usually resolves it.

Make sure you're using a 2.4 GHz Wi-Fi network. The ESP32 does not support 5 GHz.
If you entered the wrong credentials, the device will fall back to its hotspot mode (esphome-media-player). Connect to the hotspot and re-enter the correct credentials.
Move the device closer to your router to rule out signal issues.

Ensure the ESPHome integration is installed in Home Assistant.
Check that the device and Home Assistant are on the same network.
Try adding the device manually under Settings → Devices & Services → Add Integration → ESPHome using the device's IP address.

Verify the device is powered via the USB-C port with an adequate power supply (5V 2A recommended).
Try a different USB-C cable — some cables are charge-only and don't carry data for the initial flash.
Re-flash the firmware using the web installer or the ESPHome dashboard.

Make sure the media player entity supports the controls you're trying to use. Check Developer Tools → States for the supported_features attribute.
For speaker grouping, ensure you've created the template sensor — see Speaker Grouping.

See Raising an Issue for how to report a bug or request help.