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

For support, use Home Assistant's Download diagnostics action on the Adaptive Lighting config entry. The download is an on-demand snapshot of the profile's current switches and currently tracked light targets. It does not refresh group membership or predict targets a disabled profile would use after being enabled. It does not create live sensors; existing switch attributes remain the interface for automations. The reported last adaptation values are the shared manager's latest retained value for each attribute. They can come from different commands and do not represent one sent command or the current desired state.

Common Problems & Solutions

💡 Lights Only Adapt After Reloading

If lights stop adapting after you turn them on with a physical switch or a Zigbee-bound remote, check the Adaptive Lighting switch's manual_control attribute. With take_over_control: true and detect_non_ha_changes: false, a turn-on without a matching Home Assistant light.turn_on call marks the light as manually controlled. Reloading clears that state, but the next physical turn-on can trigger it again.

To adapt these turn-ons while still detecting later manual changes, enable detect_non_ha_changes and leave manual_control_on_external_turn_on disabled. This requires the light integration to report its state reliably. If you want Adaptive Lighting to keep adapting regardless of manual changes, disable take_over_control along with the options that require it: detect_non_ha_changes, adapt_only_on_bare_turn_on, and manual_control_on_external_turn_on.

This explains the physical-switch case in #1056, but not every report in that thread. If the light is not listed in manual_control, include diagnostics and debug logs from the failed turn-on when reporting it. Lights returning from unavailable after a power cut are a separate case from an off to on state change.

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

To keep detecting manual changes to lights that are already on while leaving unmatched off to on state events unchanged, enable manual_control_on_external_turn_on. Matching uses the exact context of the most recently recorded light.turn_on call. Some integrations replace or omit that context, so Adaptive Lighting cannot distinguish every physical versus Home Assistant turn-on source.

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

When Home Assistant exposes a native group's group_entities attribute, Adaptive Lighting observes individual member activations while keeping periodic updates targeted at the group. An isolated member activation receives its normal individual brightness and colour corrections, according to the enabled adaptation switches and adapt_delay, even when the group's cached settings already match. Without membership metadata, configure individual lights or a Home Assistant Light Group if member tracking is needed.

A complete light.turn_on request, scene.apply, or Home Assistant scene activation can consolidate brightness and colour independently. Each shared attribute requires every native-group member to be intended ON, eligible for that attribute, and receive the same compatible value and transition. Already-ON members count towards scene coverage. Matching brightness can use one group command while different colours remain individual; matching colour can use one group command while different brightness levels remain individual. Matching brightness and colour can share a combined group command when the same profile controls both. Separate brightness and colour profiles retain separate group commands, and competing profiles prevent grouping only for the attribute they share. Brightness grouping also works when colour adaptation is disabled. Smaller scene groups are supported when all their advertised members have one unambiguous native-group owner for each grouped attribute.

Explicit scene values keep their requested brightness, colour and transition. When both attributes are computed by Adaptive Lighting, separate_turn_on_commands divides the requested transition between their commands. Colour waits for the brightness transition plus send_split_delay, including when one attribute uses a group and the other uses individual members. Explicit scene commands retain their requested transition rather than using this adaptive split policy. Partial requests, differing values or transitions, manual overrides and incompatible capabilities prevent grouping for the affected attribute. Unrelated groups proceed concurrently, and explicit values do not wait for unrelated adaptive delays.

Explicit power settings, Home Assistant light-profile defaults and permissions remain applicable, as do only_once and skip_redundant_commands. Individual corrections follow the existing external-turn-on policy. A delayed report from an accepted command does not duplicate the brightness or colour already supplied; newer requests and OFF events supersede pending work. Integration-owned scenes that do not expose their desired states cannot provide complete coverage, and independent service calls are handled separately even if they share a context or arrive close together.

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. Native-group member observation does not expand periodic updates into individual commands. 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).
• Lonsonho ZB-RGBCW
  • Some Zigbee2MQTT/eWeLight firmware combinations do not turn the bulb on when the initial light.turn_on call includes brightness or color, although later adjustments work. Disable intercept for affected bulbs.

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