If LocalTuya stopped loading after a Home Assistant update, start with the error log. Reports against rospogrigio/localtuya describe several failures during 2026: a thread-safety error, broken light color-temperature control, and setup errors. They need different fixes. An unavailable entity on its own doesn’t identify which one you have.
This guide covers Wi-Fi Tuya devices using the LocalTuya custom integration, which controls devices on your LAN with a local key. Its optional cloud connection retrieves device details and keys; ordinary device control remains local. The 2026.1 community discussion is useful background, but the repository, installed version, and traceback are what matter for your own setup.
Tuya Zigbee devices paired directly to Zigbee2MQTT or ZHA don’t use LocalTuya or its local keys. Those devices follow a different control path.
Match the error to the right report
These are distinct reported failures. Check the exception and where it occurs before changing datapoints, resetting a device, or replacing the integration.
The thread-safety RuntimeError
Issue #2185 includes a traceback from LocalTuya 5.2.5 on Home Assistant 2026.3.1: async_dispatcher_send is called outside Home Assistant’s event-loop thread, and a RuntimeError prevents affected entities from initializing.
Home Assistant’s thread-safety documentation confirms the rule. It directs integrations to use the synchronous dispatcher_send when sending from another thread, or otherwise schedule the work on the event loop. Home Assistant has detected and blocked some unsafe calls since 2024.5, so this isn’t a rule introduced in 2026.
Similar reports predate #2185, including #1791, #1819, #1872, #2069, #2091, #2121, and #2131. Look for async_dispatcher_send and “a thread other than the event loop” in your traceback. That signature points to integration code; changing a bulb’s datapoint mapping won’t repair it.
The Kelvin-to-mireds removal
Home Assistant moved its preferred color-temperature unit from mireds to Kelvin in 2022 and deprecated the remaining mired-based light interfaces in December 2024. Its February 2026 developer notice describes removing those legacy properties and service arguments, and requiring valid color-mode information.
Issue #2151, opened in January, quotes a deprecation warning saying mired-based support would stop working in 2026.1. That warning alone doesn’t establish which controls failed on that release. Issue #2182 provides a more specific 2026.3 report: brightness still works, but Kelvin color-temperature commands are ignored or produce the wrong color.
If a tunable-white or RGB+CCT light turns on and changes brightness but won’t change color temperature, inspect this part of the integration. Switches and ordinary plugs don’t use light color-temperature properties. A light can also encounter the thread-safety error, so check for both rather than identifying the fault from its device type alone.
The config_flow IndexError
Issue #2165 reports IndexError: list index out of range in config_flow.py and ModuleNotFoundError: Platform localtuya.button not found on Home Assistant 2026.2.0. The reporter also saw a version mismatch: 5.2.3 in the interface after attempts to install 5.2.5.
This is a setup or configuration-entry failure, rather than just a light command failing. The report doesn’t establish that every 2026.2 installation has the same problem. Check that HACS is installing the repository and version you intended, and keep the full traceback when comparing it with the issue.
A thread-safety fix doesn’t automatically repair light color-temperature support or a configuration-flow error. Also check which LocalTuya fork is installed: an issue against the original repository may not apply to a fork with different code.
A fourth report, likely a different problem
Issue #2189 describes a Tuya heat pump that still worked through the vendor app and cloud integration but timed out locally. The reported environment was Home Assistant 2025.12.4 with LocalTuya 5.2.3, so it isn’t evidence that a 2026 Core upgrade caused the failure.
The reporter suspected a firmware or protocol change; the issue doesn’t prove that cause. If your log shows connection timeouts or “no datapoints found,” check reachability, protocol support, and the local key as well as integration errors. Our local-key troubleshooting guide covers that path.
Is anyone actually fixing this?
Checked on 7 October 2026, the original repository’s latest commit and release were dated 29 January 2026. Version 5.2.5 fixed a configuration-flow problem reported after Home Assistant 2025.12; its release note doesn’t claim to fix the later reports above. This gives a concrete maintenance date to the concern raised in our earlier LocalTuya comparison.
xZetsubou/hass-localtuya has a longer fork release history. Its latest listed release was 2026.7.0, dated 17 July 2026. That release includes thread-safe phase sub-sensor creation and a protocol 3.5 reconnect fix. The phase-sensor change is narrower than a general dispatcher fix; the release note doesn’t establish that every original-repository error is solved.
Hashim-K/localtuya now redirects to hashimkarim/localtuya. It advertises dispatcher/thread-safety and Kelvin fixes, with v5.2.6-hk.3 dated 15 June 2026. Its dispatcher code schedules status updates on Home Assistant’s event loop, and its light platform implements Kelvin properties. Those are relevant code changes, but they aren’t a hardware test of your device or a guarantee that an unrelated setup error is fixed.
| Project | Latest listed release at the check | What the evidence supports |
|---|---|---|
| rospogrigio/localtuya | 5.2.5, 29 January 2026 | A 2025.12 configuration-flow fix; no later release listed for the 2026 reports |
| xZetsubou/hass-localtuya | 2026.7.0, 17 July 2026 | Phase sub-sensor thread-safety and protocol 3.5 reconnect fixes; check its own tracker for your error |
| Hashim-K / hashimkarim/localtuya | v5.2.6-hk.3, 15 June 2026 | Dispatcher scheduling and Kelvin support are present in the code; device compatibility still needs checking |
Both forks use the localtuya integration domain. They replace the original custom component and cannot run beside it under that domain. Keep a full Home Assistant backup and record each device’s ID, local key, protocol version, and datapoint mappings before switching. Treat local keys as credentials.
Choosing a recovery route
First record your Home Assistant version, LocalTuya repository and version, and the first relevant exception. Then choose a route you can test and roll back.
Stay with the current installation if the impact is limited. If only color-temperature control is affected, working switches and brightness controls may be enough while you check for a suitable fix. Waiting is a choice about the impact on your setup, rather than a promise that upstream will release an update soon.
Replace LocalTuya with a fork. Follow that fork’s installation instructions and replace the custom component deliberately. Don’t delete working configuration entries merely to change the downloaded code; check the fork’s migration guidance first. Restore from your backup if the replacement cannot read your configuration or introduces new failures. After installation and a restart, test the control that originally failed, state updates, and another restart before relying on it.
Move to make-all/tuya-local. This is a separate integration with device-specific configurations, rather than LocalTuya’s manual entity/datapoint mapping. A bug in LocalTuya’s code doesn’t automatically carry over, but your exact device still needs a supported configuration. Expect to review entity IDs, automations, and dashboards during migration. The LocalTuya vs tuya-local comparison explains the setup differences.
Authentication failures need a different check. Re-pairing in Tuya or Smart Life can change the local key. A lapsed Tuya cloud API entitlement can prevent key retrieval or refresh; it doesn’t itself rotate a device’s existing key. See why a local key appears to stop working before resetting anything.
FAQ
Why did LocalTuya stop working after updating Home Assistant to 2026.1?
Check the traceback and affected controls. #2151 contains a mired-support warning, #2185 documents a dispatcher thread-safety error on 2026.3.1, and #2165 reports configuration-flow errors on 2026.2.0. None proves that every failure after 2026.1 has one cause.
Is LocalTuya still maintained?
The original repository’s latest commit and release were from January 2026 at the October check. Forks have later releases. Check their current release pages and issue trackers before choosing one.
What’s the difference between the LocalTuya forks and the original?
They share the localtuya domain but have different changes and release histories. Hashim-K’s fork includes dispatcher scheduling and Kelvin support; xZetsubou’s fork has its own feature and fix history. Select by the error and device support you need, and keep a rollback backup.
Should I switch from LocalTuya to tuya-local?
Check its support for your exact device first. It has a different setup flow and configuration catalogue, so migrating involves more than replacing a component folder. Our comparison covers the trade-offs.
Will my Tuya local keys still work if I switch to a fork?
Changing the integration doesn’t re-pair the device or issue a new key. Keep the device’s current key, ID, and protocol settings. Configuration entries and entity mappings may need migration even when the key remains valid.
Sources and limitations
This guide uses Home Assistant’s developer documentation, the linked issue reports, repository code, and release records checked on 7 October 2026. It does not report hands-on tests of these fixes. Issue reports establish reported symptoms, not the experience of every installation. Before committing to a replacement, compare your actual traceback with its tracker and test your devices through a restart.