Zone Configurator — Troubleshooting
Troubleshoot Zone Configurator setup and operation. Find guides for resolving common issues and restoring or updating firmware.
Solutions to common issues with the Zone Configurator add-on.
Add-on Issues
Add-on Won't Start
Symptoms: Add-on shows "stopped" or fails to start
Solutions:
- Check the add-on logs: Settings → Add-ons → Zone Configurator → Log
- Ensure you're running Home Assistant OS or Supervised (Core doesn't support add-ons)
- Try restarting the add-on
- Restart Home Assistant if the issue persists
Sidebar Icon Not Appearing
Solutions:
- Go to Settings → Add-ons → Zone Configurator
- Enable Show in sidebar
- Refresh your browser (Ctrl+F5 / Cmd+Shift+R)
"Ingress" or Blank Page
Symptoms: Clicking the sidebar shows a blank page or error
Solutions:
- Wait a few seconds - the UI may still be loading
- Check the add-on is running (green status)
- Clear browser cache and refresh
- Try a different browser
Device Discovery Issues
Device Not Appearing in Wizard
Symptoms: Your EPL or EP1 doesn't show in the device list
Solutions:
- Verify the device is powered on and connected to WiFi
- Check the device appears in Settings → Devices & Services → ESPHome
- Ensure the device is using compatible firmware
- Try refreshing the Zone Configurator page
"Re-sync Entities" Message
Symptoms: Warning to re-sync entities appears
Cause: Entity IDs have changed (device renamed, firmware updated, etc.)
Solution:
- Open Settings from the menu
- Click Re-sync Entities
- Wait for entity discovery to complete
Entities Missing After Discovery
Solutions:
- Click Re-sync Entities to scan again
- Verify the ESPHome integration is working in Home Assistant
- Check the device logs in ESPHome Dashboard
- Restart the device and try again
Entity Mapping Issues
Entities Showing "Review" Status
Symptoms: Orange "Review" label appears next to some entities
Cause: Multiple entities matched equally, and the system couldn't determine which is correct
Solution:
- Click the dropdown next to the entity
- Look at the entity IDs - choose the one that matches your device name
- Entities marked
[disabled]or[hidden]may not be the best choice - After selecting, the icon changes to ✎ to confirm your choice
"Disabled in HA" Warning
Symptoms: Yellow warning banner says entities are disabled in Home Assistant
Cause: The matched entities exist but are disabled in Home Assistant's entity registry
Why this happens:
- ESPHome creates many diagnostic entities disabled by default
- You may have manually disabled entities previously
- Firmware updates can change entity defaults
Solution:
- Note which entities show "Disabled in HA" (yellow tag)
- Go to Home Assistant → Settings → Devices & Services
- Find your device under ESPHome
- Click on the device to see all entities
- Find the disabled entity (shown greyed out)
- Click on it and select Enable
- Return to Zone Configurator - it will work without re-syncing
Note: You can save mappings with disabled entities. Once you enable them in HA, Zone Configurator will work automatically.
"Entity not found in registry" Error
Symptoms: Validation fails with "Entity not found in registry"
Causes:
- Entity was deleted from Home Assistant
- Device was removed and re-added with new entity IDs
- Entity ID changed after firmware update
Solution:
- Click Re-discover entities to scan again
- If the entity truly doesn't exist, select a different one from the dropdown
- Check the device is still present in Home Assistant
"Entity belongs to a different device" Error
Symptoms: Validation fails with "Entity belongs to a different device"
Cause: You selected an entity from a different EPL/EP1 device
Solution:
- Click the ✎ icon to change the mapping
- Look for entity IDs containing your device name
- Select an entity that belongs to the correct device
Wrong Entity Auto-Selected
Symptoms: Auto-discovery picked the wrong entity (e.g., zone entity instead of main occupancy)
Why this happens:
- Similar entity names across zones, targets, or sensors
- Device renamed after initial setup
- Multiple devices with similar names
Solution:
- Click the ✎ icon next to the incorrect mapping
- Review the dropdown - entities are sorted by match likelihood
- Look for the entity that matches what you expect:
- Main occupancy: Usually ends in
_occupancywithout zone numbers - Zone occupancy: Contains
_zone_1_,_zone_2_, etc. - Target positions: Contains
_target_1_x,_target_1_y, etc.
- Main occupancy: Usually ends in
- Select the correct entity
Missing Zone or Tracking Entities
Symptoms: Zone or target tracking entities don't appear in discovery
Possible causes:
- Firmware doesn't support zones (older versions)
- Entities are disabled in Home Assistant
- Wrong device profile selected
Solutions:
- Check your firmware version supports the features you need
- Look for disabled entities in Home Assistant and enable them
- If using a custom firmware, ensure zone entities are defined
- Re-run discovery after enabling entities
When to Re-sync Entities
You should re-sync entities when:
- You renamed your device in Home Assistant
- You updated the device firmware
- Entities appear missing or incorrectly mapped
- Zone Configurator shows stale data
- You see the "Re-sync entities" warning message
To re-sync:
- Go to Settings in Zone Configurator
- Click Re-sync Entities for the affected room
- Review and confirm the mappings
- Click Continue to save
Entity Discovery Shows No Entities
Symptoms: Discovery runs but finds zero entities
Causes:
- Device is offline
- ESPHome integration not working
- Device ID mismatch
Solutions:
- Check device status in Settings → Devices & Services → ESPHome
- Verify the device shows entities when you click on it in HA
- Try restarting the ESPHome integration
- Restart the device and try discovery again
- Check add-on logs for specific error messages
Tracking Issues
Targets Not Appearing
Symptoms: No dots appear on the live view even when someone is in the room
Solutions:
- Verify occupancy shows "Detected" in Home Assistant
- Check the device is within range (EPL: up to 6m)
- Ensure nothing is blocking the sensor
- Try restarting the device
Target Position Is Wrong
Symptoms: Dots appear but in the wrong location
Solutions:
- Verify device placement in Room Builder matches physical installation
- Check device rotation is set correctly
- Adjust installation angle if sensor is tilted
- Recalibrate by repositioning the device icon
Tracking Jumps or Jitters
Symptoms: Target dots move erratically
Possible causes:
- Reflective surfaces (mirrors, metal, glass)
- Interference from other devices
- Target at edge of detection range
Solutions:
- Reduce max detection distance
- Add exclusion zones for problematic areas
- Check for sources of interference
Zone Issues
Zones Not Saving to Device
Symptoms: "Save to Device" fails or zones disappear after restart
Solutions:
- Ensure the device is online and connected
- Check Home Assistant can communicate with the device
- Verify you're not exceeding the 4-zone limit
- Look for errors in the add-on logs
Zone Not Activating
Symptoms: Target is visually inside zone but zone doesn't show occupied
Solutions:
- Watch the live view - is the target dot actually inside the zone?
- Zone coordinates may need adjustment
- Check zone type isn't set to "Exclusion"
- Verify zones were saved to device
Zone Always Shows Occupied
Symptoms: Zone stays active even when room is empty
Solutions:
- Zone may overlap the sensor position - move it further away
- Check for false triggers (moving objects, pets, fans)
- Add exclusion zones to mask problem areas
- Reduce zone size
WebSocket/Connection Issues
"Disconnected" Status
Symptoms: Connection indicator shows red, no live updates
Solutions:
- Check the add-on is still running
- Verify your device is online in Home Assistant
- Refresh the page
- Restart the add-on
Slow or Laggy Updates
Symptoms: Target movement is delayed or choppy
Possible causes:
- Network latency
- Browser performance
- Too many entities being tracked
Solutions:
- Try a different browser
- Close other browser tabs
- Check your network connection
- Restart the add-on
Room Builder Issues
Room Outline Not Saving
Solutions:
- Ensure you completed the shape (clicked first point or pressed Enter)
- Check for any error messages
- Try a simpler room shape
Furniture Disappearing
Solutions:
- Furniture may be outside the visible area - zoom out
- Check display settings haven't hidden furniture
- Re-add the furniture item
Still Need Help?
If you're still experiencing issues:
- Check add-on logs: Settings → Add-ons → Zone Configurator → Log
- Check device logs: ESPHome Dashboard → Logs
- Join our Discord: Get help from the community
- Report a bug: GitHub Issues for the add-on repository