HACS Integration Not Appearing & Adaptive Lighting Conflicts

Overview

After installing an integration via HACS, it sometimes fails to appear in Home Assistant for configuration. This guide provides a step-by-step troubleshooting process, using the popular Adaptive Lighting integration as a case study for common conflicts.

Core Troubleshooting Steps

1. Clear Browser Cache: Your browser may have cached an old version of the Home Assistant frontend. Force a hard refresh (Ctrl+Shift+R or Cmd+Shift+R).
2. Restart Home Assistant: A full restart is required for Home Assistant to load new custom components. Go to Settings > System and click Restart.
3. Check HA Logs for Errors: Look for errors related to the specific integration in Settings > System > Logs. This can provide clues about dependency issues or misconfigurations.

Case Study: Adaptive Lighting Not Appearing

This is a common scenario. You install Adaptive Lighting in HACS, restart, but it’s nowhere to be found under Settings > Devices & Services > Add Integration.

The Conflict: custom_components Naming

A frequent cause is a conflict with another custom component that creates an adaptive_lighting folder inside custom_components. The official Adaptive Lighting integration also uses this name, leading to a conflict.

How to Fix It

1. Identify the Conflicting Component: Check your /config/custom_components/ directory for any folder named adaptive_lighting that is NOT the HACS installation.
2. Rename or Remove: If you find a duplicate, either rename its folder and update its configuration, or remove it if it’s no longer needed.
3. Reinstall & Restart: After resolving the conflict, you may need to reinstall the desired integration through HACS and restart Home Assistant again.

General Checklist for Missing HACS Integrations

• Is HACS itself working? Can you browse other repositories?
• Did you restart Home Assistant? Not just reload configuration.
• Is the integration compatible? Check the HACS repository for the required Home Assistant version.
• Are there any errors in the logs? This is your most valuable diagnostic tool.
• Is there a naming conflict in your custom_components folder?

Example: Finding Errors in Logs

If you see an error like this, it points to a problem with the component’s code or its dependencies:

ERROR (MainThread) [homeassistant.loader] Error loading custom_components.adaptive_lighting.light: ImportError: cannot import name '''ATTR_PROFILE_NAME''' from '''custom_components.adaptive_lighting.const'''

This indicates a problem within the Adaptive Lighting component itself, which could be due to an outdated version or a conflict.

Best Practices

• Keep HACS Updated: Regularly update HACS to ensure compatibility with the latest Home Assistant releases.
• Read the Docs: Before installing, quickly read the integration’s documentation for any special instructions.
• Backup Before Installing: Always have a recent backup before adding new custom components.

By following these steps, you can resolve most issues with HACS integrations not appearing and enjoy the vast library of community-developed enhancements for Home Assistant.