Since updating to HA 2025.3 brightness is no longer exposed for lights that does not include supported_color_modes.

[swesharkie]

Feedback

The current documentation states the following:

supported_color_modes list (Optional)
A list of color modes supported by the list. Possible color modes are onoff, brightness, color_temp, hs, xy, rgb, rgbw, rgbww, white. Note that if onoff or brightness are used, that must be the only value in the list.

First, I'd like to suggest an addendum to this stating that it is not really optional (debatable though, if it's not included the light will only expose on/off) if the light has any feature, brightness for instance.

Secondly, I'd like to argue that the behavior of this is not exactly logical. Onoff and brightness should not be called color_mode.
Also, if the light support any feature so Z2M (for instance) includes this array, say color_temp, then brightness also works even if not included (since brightness must be the only value if included). I'm guessing that brightness is assumed if any feature is included here.

Some clarification on the two caveats above should be included in my opinion.

My suggested edit in bold:

supported_color_modes list (Optional)
A list of color modes supported by the light. Possible color modes are onoff, brightness, color_temp, hs, xy, rgb, rgbw, rgbww, white. Note that if onoff or brightness are used, that must be the only value in the list.
Note that this is not optional for lights only supporting brightness.
Default value if omitted is onoff only.
Note that if color_temp, hs, xy, rgb, rgbw, rgbww is used, brightness is assumed to also be supported.

URL

https://www.home-assistant.io/integrations/light.mqtt/

Version

2025.2.5

Additional information

No response

[home-assistant]

Hey there @emontnemery, @jbouwh, @bdraco, mind taking a look at this feedback as it has been labeled with an integration (mqtt) you are listed as a code owner for? Thanks!

Code owner commands

Code owners of mqtt can trigger bot actions by commenting:

• @home-assistant close Closes the feedback.
• @home-assistant rename Awesome new title Renames the feedback.
• @home-assistant reopen Reopen the feedback.
• @home-assistant unassign mqtt Removes the current integration label and assignees on the feedback, add the integration domain after the command.
• @home-assistant add-label needs-more-information Add a label (needs-more-information) to the feedback.
• @home-assistant remove-label needs-more-information Remove a label (needs-more-information) on the feedback.

[jbouwh]

See home-assistant/core#136996 This is something to be solved in Zigbee2Mqtt.
It is optional, as lights without color or color_temp support should still work.

[jbouwh]

home-assistant/core#139585 will allow to use the brightness flag without supported_color_modes. That should solve any confusion.

[swesharkie]

See home-assistant/core#136996 This is something to be solved in Zigbee2Mqtt. It is optional, as lights without color or color_temp support should still work.

I do agree that the actual fix for our current issue should be in Z2M.
My only argument here was to clarify the documentation to reflect how "optional" the key actually is, that some caveats are included depending on what you expect to work. My intention was not to suggest that it should not be optional since some lights don't have any modes at all (then again, why is onoff in there then? ;)..)
If I suddenly were missing brightness, I wouldn't logically look in supported_color_modes for the solution. Even if it technically is noted there.

Either way, it was just a suggestion :).

home-assistant/core#139585 will allow to use the brightness flag without supported_color_modes. That should solve any confusion.

Well then it gets sorted either way, it's not a perfect solution since the features are spread out but it's more in line with how the config expects certain features to be there regardless (for instance brightness is assumed if xy and color_temp is included in color_modes).

I'm going to close this, this is fine. I appreciate your time to look into this and your reply, thank you.