adaptive-lighting/docs/troubleshooting.md

---
icon: lucide/life-buoy
---

# Troubleshooting

This guide covers common issues and their solutions when using Adaptive Lighting.

## Enable Debug Logging

<!-- CODE:START -->
<!-- import sys; sys.path.insert(0, 'custom_components/adaptive_lighting') -->
<!-- from docs_gen import get_troubleshooting_intro -->
<!-- print(get_troubleshooting_intro()) -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
Encountering issues? Enable debug logging in your `configuration.yaml`:

```yaml
logger:
  default: warning
  logs:
    custom_components.adaptive_lighting: debug
```

After the issue occurs, create a new issue report with the log (`/config/home-assistant.log`).

<!-- OUTPUT:END -->

## Common Problems & Solutions

<!-- CODE:START -->
<!-- import sys; sys.path.insert(0, 'custom_components/adaptive_lighting') -->
<!-- from docs_gen import get_common_problems -->
<!-- print(get_common_problems()) -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
#### :bulb: Lights Not Responding or Turning On by Themselves

Adaptive Lighting sends more commands to lights than a typical human user would. If your light control network is unhealthy, you may experience:

- Laggy manual commands (e.g., turning lights on or off).
- Unresponsive lights.
- Home Assistant reporting incorrect light states, causing Adaptive Lighting to inadvertently turn lights back on.

Most issues that appear to be caused by Adaptive Lighting are actually due to unrelated problems.
Addressing these issues will significantly improve your Home Assistant experience.

In case lights are suddenly turning on by themselves, this is most likely due to the light incorrectly reporting an "on" state to Home Assistant, leading to an undesired Adaptive Lighting action.
To prevent adapting in cases *where the state of the light is suddenly "on" and only adapt if there is an associated `light.turn_on` service call*, set `detect_non_ha_changes: false`.

#### :signal_strength: WiFi Networks

Ensure your light bulbs have a strong WiFi connection. If the signal strength is less than -70dBm, the connection may be weak and prone to dropping messages.

#### :spider_web: Zigbee, Z-Wave, and Other Mesh Networks

Mesh networks typically require powered devices to act as routers, relaying messages back to the central coordinator (the radio connected to Home Assistant).
Philips lights usually function as routers, while Ikea, Sengled, and generic Tuya bulbs often do not.
If devices become unresponsive or fail to respond to commands, Adaptive Lighting can exacerbate the issue.
Use network maps (available in ZHA, zigbee2mqtt, deCONZ, and ZWaveJS UI) to evaluate your network health.
Smart plugs can be an affordable way to add more routers to your network.

For most Zigbee networks, **using groups is essential for optimal performance**.
For example, if you want to use Adaptive Lighting in a hallway with six bulbs, adding each bulb individually to the Adaptive Lighting configuration could overwhelm the network with commands.
Instead, create a group in your Zigbee software (not a regular Home Assistant group) and add that single group to the Adaptive Lighting configuration.
This sends a single broadcast command to adjust all bulbs, improving response times and keeping the bulbs in sync.

As a rule of thumb, if you always control lights together (e.g., bulbs in a ceiling fixture), they should be in a Zigbee group.
Expose only the group (not individual bulbs) in Home Assistant Dashboards and external systems like Google Home or Apple HomeKit.

> :warning: **If you control lights individually, `manual_control` cannot behave correctly! If you need to control lights individually as well, use a [Home Assistant Light Group](https://www.home-assistant.io/integrations/group/).**

#### :rainbow: Light Colors Not Matching

Bulbs from different manufacturers or models may have varying color temperature specifications. For instance, if you have two Adaptive Lighting configurations—one with only Philips Hue White Ambiance bulbs and another with a mix of Philips Hue White Ambiance and Sengled bulbs—the Philips Hue bulbs may appear to have different color temperatures despite having identical settings.

To resolve this:

1.  Include only bulbs of the same make and model in a single Adaptive Lighting configuration.
2.  Rearrange bulbs so that different color temperatures are not visible simultaneously.

#### :bulb: Bulb-Specific Issues

These lights are known to exhibit disadvantageous behaviour due to firmware bugs, insufficient functionality, or hardware limitations:

- [Sengled Z01-A19NAE26](https://www.zigbee2mqtt.io/devices/Z01-A19NAE26.html#sengled-z01-a19nae26)
  - Unexpected turn-ons: If Adaptive Lighting sends a long transition time (like the default 45 seconds), and the bulb is turned off during that time, it may turn back on after approximately 10 seconds to continue the transition command. Since the bulb is turning itself on, there will be no obvious trigger in Home Assistant or other logs indicating the cause of the light turning on. To fix this, set a much shorter `transition` time, such as 1 second.
  - Heat sensitivity: Additionally, these bulbs may perform poorly in enclosed "dome" style ceiling lights, particularly when hot. While most LEDs (even non-smart ones) state in the fine print that they do not support working in enclosed fixtures, in practice, more expensive bulbs like Philips Hue generally perform better. To resolve this issue, move the problematic bulbs to open-air fixtures.
- Ikea Tradfri bulbs/drivers (and related Ikea smart light products)
  - Unsupported simultaneous transition of brightness and color: When receiving such a command, they switch the brightness instantly and only transition the color. To get smooth transitions of both brightness and color, enable `separate_turn_on_commands`.
  - Unresponsiveness during color transitions: No other commands are processed during an ongoing color transition, e.g., turn-off commands are ignored and lights stay on despite being reported as off to Home Assistant. The default config with long transitions thus results in long periods of unresponsiveness. To work around this, disable transitions by setting `transition` to `0`, and increase the adaptation frequency by setting `interval` to a short time, e.g., `15` seconds, to retain the impression of smooth continuous adaptations. Keeping the `initial_transition` is recommended for a smooth fade-in (lights are usually not turned off momentarily after being turned on, in which case a short period of unresponsiveness is tolerable).

<!-- OUTPUT:END -->

---

## Additional Troubleshooting Tips

### Lights Flickering

If your lights flicker when Adaptive Lighting adjusts them:

1. **Increase transition time**: Set `transition: 60` or higher
2. **Reduce adaptation frequency**: Set `interval: 120` or higher
3. **Enable `skip_redundant_commands`**: This reduces unnecessary commands

```yaml
adaptive_lighting:
  - name: "Anti-flicker"
    lights:
      - light.problem_light
    transition: 60
    interval: 120
    skip_redundant_commands: true
```

### Lights Not Adapting

If lights aren't being adapted:

1. Check that the main switch is on: `switch.adaptive_lighting_<name>`
2. Check that the light isn't marked as manually controlled (check switch attributes)
3. Verify the light is in the configuration's `lights` list
4. Check debug logs for errors

### Color Temperature Looks Wrong

Different bulb manufacturers have varying color temperature implementations:

1. **Group similar bulbs**: Only include bulbs of the same make/model in one configuration
2. **Adjust the range**: Some bulbs may need narrower `min_color_temp`/`max_color_temp` ranges
3. **Use RGB instead**: Set `prefer_rgb_color: true` for more consistent colors

### Slow Response to Changes

If adaptation seems delayed:

1. **Reduce interval**: Set `interval: 30` for faster updates
2. **Enable intercept**: Set `intercept: true` for instant adaptation on turn-on
3. **Check network**: Ensure your light network is healthy (see WiFi/Zigbee sections above)

### Integration Not Loading

If Adaptive Lighting doesn't load:

1. Check that `adaptive_lighting:` is in your `configuration.yaml`
2. Verify the integration is installed correctly in `custom_components/`
3. Check the Home Assistant logs for errors
4. Ensure you're running a compatible Home Assistant version (2024.12.0+)

## Getting Help

If you're still having issues:

1. Enable debug logging and capture the relevant logs
2. Open an issue on [GitHub](https://github.com/basnijholt/adaptive-lighting/issues)
3. Include:
   - Your configuration (redact sensitive info)
   - Debug logs
   - Home Assistant version
   - Description of expected vs actual behavior