# 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

---

**Documents**

- [EP1 vs EPL: Which Sensor is Right for You?](https://docs.everythingsmart.io/s/products/doc/ep1-vs-epl-which-sensor-is-right-for-you-5B3RxiY3Kp)
- [Everything Presence One (EP1)](https://docs.everythingsmart.io/s/products/doc/everything-presence-one-ep1-3R178yZSUP)
- [Everything Presence Pro](https://docs.everythingsmart.io/s/products/doc/everything-presence-pro-nh3fIXmow9)
- [Everything Presence Lite (EPL)](https://docs.everythingsmart.io/s/products/doc/everything-presence-lite-epl-ZVnBzYzuX2)
- [Zone Configurator](https://docs.everythingsmart.io/s/products/doc/zone-configurator-93b9scGsa2)
- [Knowledge Base Articles](https://docs.everythingsmart.io/s/products/doc/knowledge-base-articles-KnRRmk4zvt)