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

Encountering issues? Enable debug logging in your configuration.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).

Common Problems & Solutions

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

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

🕸️ 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). Most modern lights function as routers, very early models may 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.

⚠️ 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.

When mixing group types, avoid nesting: do not add integration-level groups (e.g., Zigbee2MQTT groups) to a Home Assistant Light Group that is managed by Adaptive Lighting, and do not nest Home Assistant Light Groups inside each other. Adaptive Lighting cannot expand an integration-level group into its member lights, and nested groups make it unpredictable which entity Adaptive Lighting tracks and adapts, which can prevent lights from being adapted at all (see #1378). Instead, add the individual light entities or a single Zigbee group directly to the Adaptive Lighting configuration. Also note that bulbs turned on via a Zigbee group broadcast may briefly flash their last (cached) brightness and color before the adapted values arrive; this happens inside the bulbs and cannot be prevented by Home Assistant or Adaptive Lighting.

🌈 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-Specific Issues

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

• 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).

Getting Help

If you're still having issues:

1. Enable debug logging and capture the relevant logs
2. Open an issue on GitHub
3. Include:
   • Your configuration (redact sensitive info)
   • Debug logs
   • Home Assistant version
   • Description of expected vs actual behavior