Raising an Issue
If you've gone through Troubleshooting and still need help, open an issue on GitHub.
Before you open an issue
- Search existing issues — your problem may already be reported or resolved: GitHub Issues
- Check you're on the latest firmware — re-flash using the web installer to make sure you have the latest version.
What to include
To help diagnose the problem quickly, include the following:
- Device — which hardware you're using (e.g. ESP32-S3 4848S040 4", ESP32-P4 JC8012P4A1 10.1")
- Installation method — web installer or manual ESPHome setup
- Description — what you expected vs. what happened
- Steps to reproduce — how to trigger the issue
- Logs — ESPHome device logs from the dashboard or Home Assistant (go to Settings → Devices & Services → ESPHome → your device → Logs)
- Screenshots — photos of the screen if it's a display issue