Troubleshooting

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:

1. Check the add-on logs: Settings → Add-ons → Zone Configurator → Log

2. Ensure you're running Home Assistant OS or Supervised (Core doesn't support add-ons)

3. Try restarting the add-on

4. Restart Home Assistant if the issue persists

Sidebar Icon Not Appearing

Solutions:

1. Go to Settings → Add-ons → Zone Configurator

2. Enable Show in sidebar

3. Refresh your browser (Ctrl+F5 / Cmd+Shift+R)

"Ingress" or Blank Page

Symptoms: Clicking the sidebar shows a blank page or error

Solutions:

1. Wait a few seconds - the UI may still be loading

2. Check the add-on is running (green status)

3. Clear browser cache and refresh

4. 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:

1. Verify the device is powered on and connected to WiFi

2. Check the device appears in Settings → Devices & Services → ESPHome

3. Ensure the device is using compatible firmware

4. 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:

1. Open Settings from the menu

2. Click Re-sync Entities

3. Wait for entity discovery to complete

Entities Missing After Discovery

Solutions:

1. Click Re-sync Entities to scan again

2. Verify the ESPHome integration is working in Home Assistant

3. Check the device logs in ESPHome Dashboard

4. 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:

1. Click the dropdown next to the entity

2. Look at the entity IDs - choose the one that matches your device name

3. Entities marked [disabled] or [hidden] may not be the best choice

4. 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:

1. Note which entities show "Disabled in HA" (yellow tag)

2. Go to Home Assistant → Settings → Devices & Services

3. Find your device under ESPHome

4. Click on the device to see all entities

5. Find the disabled entity (shown greyed out)

6. Click on it and select Enable

7. 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:

1. Click Re-discover entities to scan again

2. If the entity truly doesn't exist, select a different one from the dropdown

3. 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:

1. Click the ✎ icon to change the mapping

2. Look for entity IDs containing your device name

3. 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:

1. Click the ✎ icon next to the incorrect mapping

2. Review the dropdown - entities are sorted by match likelihood

3. Look for the entity that matches what you expect:

   • Main occupancy: Usually ends in _occupancy without zone numbers

   • Zone occupancy: Contains _zone_1_, _zone_2_, etc.

   • Target positions: Contains _target_1_x, _target_1_y, etc.

4. 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:

1. Check your firmware version supports the features you need

2. Look for disabled entities in Home Assistant and enable them

3. If using a custom firmware, ensure zone entities are defined

4. 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:

1. Go to Settings in Zone Configurator

2. Click Re-sync Entities for the affected room

3. Review and confirm the mappings

4. 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:

1. Check device status in Settings → Devices & Services → ESPHome

2. Verify the device shows entities when you click on it in HA

3. Try restarting the ESPHome integration

4. Restart the device and try discovery again

5. 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:

1. Verify occupancy shows "Detected" in Home Assistant

2. Check the device is within range (EPL: up to 6m)

3. Ensure nothing is blocking the sensor

4. Try restarting the device

Target Position Is Wrong

Symptoms: Dots appear but in the wrong location

Solutions:

1. Verify device placement in Room Builder matches physical installation

2. Check device rotation is set correctly

3. Adjust installation angle if sensor is tilted

4. 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:

1. Reduce max detection distance

2. Add exclusion zones for problematic areas

3. Check for sources of interference

Zone Issues

Zones Not Saving to Device

Symptoms: "Save to Device" fails or zones disappear after restart

Solutions:

1. Ensure the device is online and connected

2. Check Home Assistant can communicate with the device

3. Verify you're not exceeding the 4-zone limit

4. Look for errors in the add-on logs

Zone Not Activating

Symptoms: Target is visually inside zone but zone doesn't show occupied

Solutions:

1. Watch the live view - is the target dot actually inside the zone?

2. Zone coordinates may need adjustment

3. Check zone type isn't set to "Exclusion"

4. Verify zones were saved to device

Zone Always Shows Occupied

Symptoms: Zone stays active even when room is empty

Solutions:

1. Zone may overlap the sensor position - move it further away

2. Check for false triggers (moving objects, pets, fans)

3. Add exclusion zones to mask problem areas

4. Reduce zone size

WebSocket/Connection Issues

"Disconnected" Status

Symptoms: Connection indicator shows red, no live updates

Solutions:

1. Check the add-on is still running

2. Verify your device is online in Home Assistant

3. Refresh the page

4. 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:

1. Try a different browser

2. Close other browser tabs

3. Check your network connection

4. Restart the add-on

Room Builder Issues

Room Outline Not Saving

Solutions:

1. Ensure you completed the shape (clicked first point or pressed Enter)

2. Check for any error messages

3. Try a simpler room shape

Furniture Disappearing

Solutions:

1. Furniture may be outside the visible area - zoom out

2. Check display settings haven't hidden furniture

3. Re-add the furniture item

Still Need Help?

If you're still experiencing issues:

1. Check add-on logs: Settings → Add-ons → Zone Configurator → Log

2. Check device logs: ESPHome Dashboard → Logs

3. Join our Discord: Get help from the community

4. Report a bug: GitHub Issues for the add-on repository