Homematic IP Local 2.8.1 does not start up on Home Assistant 2026.7.1

[martinkellerka]

I agree to the following

• I have read the documentation
• I have read the troubleshooting documentation, and tried to identify/solve the issue by myself.
• I have read the Glossary and understand the difference between Integration, App, and Backend
• I am aware of the latest release notes
• I am aware that an integration that was installed via HACS also needs to be updated via HACS
• The Backend (CCU/Homegear/...) is working as expected, devices are taught in and are controllable by its own UI.
• I am running the latest version of the custom_component (and Home Assistant)
• This is NOT a frontend/UI issue (those belong in the homematicip_local_frontend repo)
• I have attached the raw diagnostics (.json) and log files and have NOT replaced them with an AI-generated analysis (we analyze the raw data ourselves; pasted AI conclusions may be disregarded)

The problem

I just updated vom integration version 2.8.0 to 2.8.1 and it does not start anymore. Downgrading again to 2.8.0 resolves the issue and the integration starts up fine.

What version of Homematic(IP) Local for OpenCCU has the issue?

2.8.1

What was the last working version of Homematic(IP) Local for OpenCCU?

2.8.0

What type of installation are you running?

Home Assistant OS

What type of installation are you running for your Homematic backend?

OpenCCU HA-App

Which version of your Homematic backend are you running?

3.87.6.20260614

What hardware are you running for your system?

Pi5

Which config details do you use

• TLS
• callback data (see)

Which interfaces do you use?

• Homematic IP
• Homematic (Bidcos-RF)
• Groups (Heating-Group)
• BidCos-Wired (HM-Wired)
• CuXD
• CCU-Jack

Diagnostics information (no logs here!)

I did not find a .json diagnostic file, only HA logs.

Log file (preferably DEBUG log)

Logger: custom_components.homematicip_local
Quelle: custom_components/homematicip_local/init.py:128
Integration: Homematic(IP) Local for OpenCCU (Dokumentation, Probleme)
Erstmals aufgetreten: 09:35:19 (1 Vorkommnis)
Zuletzt protokolliert: 09:35:19

This release of Homematic(IP) Local for OpenCCU requires aiohomematic version 2026.7.1, but found version 2026.7.2. Looks like HA has a problem with dependency management. This is NOT an issue of the integration.

Logger: custom_components.homematicip_local
Quelle: custom_components/homematicip_local/init.py:135
Integration: Homematic(IP) Local for OpenCCU (Dokumentation, Probleme)
Erstmals aufgetreten: 09:35:19 (1 Vorkommnis)
Zuletzt protokolliert: 09:35:19

Homematic(IP) Local for OpenCCU setup blocked

Additional information

I did not find further logfiles or information. I hope this helps anyway.

[github-actions]

Automatic Issue Analysis

Summary: Integration version 2.8.1 fails to start due to a dependency version mismatch. The integration requires aiohomematic 2026.7.1 but Home Assistant installed version 2026.7.2 instead. This is a Home Assistant dependency management issue, not an integration bug. The integration correctly blocks startup to prevent compatibility issues. Version 2.8.0 works fine. Diagnostics file is missing but may not be critical for this specific startup issue.

⚠️ Missing Required Information

Meaningful support is only possible if all required information is provided!

Missing:

• ❌ Integration diagnostics (.json file) - Download via: Settings → Devices → Select integration → Download diagnostics

⚠️ Issues without this information cannot be processed and may be closed.

Exception: For initial setup issues, diagnostics may not be available yet.

Additional Missing Information

• interface_selection: The 'Which interfaces do you use?' section is completely empty - no checkboxes are selected. This information helps understand the setup configuration.
• complete_log: Only two specific error messages were provided. The complete Home Assistant log file (preferably with DEBUG logging enabled) would be helpful to see the full startup sequence and any additional context.

Attachment Analysis

✅ Log data analyzed.

Findings:

• ❌ [Other] Dependency version mismatch detected: Integration 2.8.1 requires aiohomematic 2026.7.1, but Home Assistant installed version 2026.7.2. The integration explicitly blocks startup when dependency versions don't match.
  • 💡 Recommendation: This is a known dependency management issue with Home Assistant. The error message correctly identifies this as a Home Assistant problem, not an integration issue. Workarounds: 1) Continue using version 2.8.0 until HA dependency management resolves this, 2) Wait for a potential hotfix release 2.8.2, or 3) Check if clearing the HA cache and restarting helps force proper dependency resolution.
• ℹ️ [Other] The integration has a strict version check that blocks startup when the aiohomematic library version doesn't exactly match the required version. This is a safety mechanism to prevent compatibility issues.
  • 💡 Recommendation: This is expected behavior. The integration is protecting against potential incompatibilities by refusing to start with a mismatched dependency version.

Helpful Documentation

The following documentation pages might be helpful:

• troubleshooting
  Contains information about common startup and installation issues
• releases
  Check release notes for version 2.8.1 for any known issues or dependency requirements
• homematicip_local_readme
  General installation and setup guidance

Similar Issues and Discussions

The following issues or discussions might be relevant:

• ✅ CUXD Geräte nach Update auf 2.8.0 / 2.8.1 nicht mehr verfügbar #3273: CUXD Geräte nach Update auf 2.8.0 / 2.8.1 nicht mehr verfügbar
• ✅ Nach Update auf 2.8.0 sind bei Thermostaten aktivierte Entitäten wieder deaktiviert, nach Aktivierung mit anderer Entity ID #3272: Nach Update auf 2.8.0 sind bei Thermostaten aktivierte Entitäten wieder deaktiviert, nach Aktivierung mit anderer Entity ID
• ✅ HM-LC-Bl1PBU-FM enters communication error when using cover.set_cover_position via Home Assistant (CCU WebUI works fine) #3270: HM-LC-Bl1PBU-FM enters communication error when using cover.set_cover_position via Home Assistant (CCU WebUI works fine)
• ✅ Integration does not start because https://wheels.home-assistant.io/musllinux-index/openccu-data/ times out #3261: Integration does not start because https://wheels.home-assistant.io/musllinux-index/openccu-data/ times out

---

This analysis was generated automatically. For questions or support, please use the discussions.

[martinkellerka]

I know the log says this is not an issue of the integration, but why is 2.8.0 working then?

Also I do have nothing with 2026.7.2 installed, no Beta, nothing. I am on released HA 2026.7.1