HACS Visibility Troubleshooting Checklist

Overview

This checklist addresses common reasons why HACS (Home Assistant Community Store) may not appear in the sidebar or integrations list after installation, compiled from community discussions and official documentation.

Phase 1: Initial Checks (Browser & Restart)

1. Clear Browser Cache / Hard Refresh

Reason: Home Assistant frontend often caches resources. HACS, being a custom component, requires a fresh reload.

Action: Perform a hard refresh (Ctrl+Shift+R or Cmd+Shift+R) or completely clear your browser cache.

2. Restart Home Assistant

Reason: HACS is a custom integration that requires a full Home Assistant restart (not just a configuration reload) to initialize correctly.

Action: Go to Settings > System > Restart.

Phase 2: Installation & Configuration Verification

3. Verify HACS Integration Status

Reason: HACS might be installed but not configured or might have a configuration error.

Action: Navigate to Settings > Devices & Services > Integrations. Search for HACS.

Expected: HACS should be listed without errors.

Troubleshooting: If it shows a configuration error, try to re-configure it or check the Home Assistant logs for specific errors.

4. Complete GitHub Authentication (OAuth Flow)

Reason: HACS requires successful authentication with GitHub to function and appear.

Action: If HACS is listed but not fully set up, remove it and re-add it via + Add Integration.

Checklist:

• Copy the device code provided by HA
• Navigate to the GitHub device activation link
• Sign in and authorize HACS
• Return to HA and click ‘Submit’/‘Finish’

5. Check custom_components Folder Structure

Reason: Incorrect file placement prevents HA from loading the integration.

Action: Verify that the HACS files are located correctly in /config/custom_components/hacs/.

Troubleshooting: If manual installation was used, ensure the contents of the HACS zip file were copied directly into the hacs folder, not nested inside another folder.

Phase 3: Advanced Troubleshooting (File System & Network)

6. Check for File System Errors (.storage)

Reason: Critical errors during HACS updates or restarts can corrupt its configuration files, leading to a NotADirectoryError in the logs and HACS disabling itself.

Action: Access your Home Assistant configuration directory (e.g., via Samba or SSH).

Troubleshooting: Look for the .storage folder. If logs show errors related to /config/.storage/hacs/120370503.hacs (or similar), try removing or renaming the hacs file/folder inside .storage and restart HA.

7. Diagnose Network Connectivity Issues (ISP Blocking)

Reason: HACS needs to connect to data-v2.hacs.xyz:443 to fetch repository lists. Some ISPs or local network security features (like ‘shields’ or firewalls) block this domain, leading to an empty HACS store or connection errors (SSL record layer failure).

Action: Test connectivity from the HA host environment (if possible) using telnet data-v2.hacs.xyz 443 or nc -vz data-v2.hacs.xyz 443.

Troubleshooting: If connectivity fails or a wget returns an ISP redirect page instead of data, check your router/ISP security settings and whitelist data-v2.hacs.xyz.

8. Check for Update Conflicts

Reason: Updating Home Assistant Core or HACS itself can sometimes cause temporary conflicts or deprecation warnings that prevent HACS from loading.

Action: If the issue occurred immediately after an update, check GitHub issues for the specific HACS version and HA Core version combination. Restoring from a backup might be the only immediate remedy.

Summary of Common Gotchas

Quick Reference Commands

Test HACS Connectivity

# From HA host (if accessible)
telnet data-v2.hacs.xyz 443
# Or
nc -vz data-v2.hacs.xyz 443

Check HACS Logs

# In HA Configuration > Logs, look for:
# - NotADirectoryError
# - SSL record layer failure
# - Authentication errors

When All Else Fails

If you’ve tried all the above steps and HACS still won’t appear:

1. Backup your configuration (especially /config/custom_components/ and /config/.storage/)
2. Perform a clean reinstall of HACS
3. Check GitHub issues for your specific HA and HACS versions
4. Consider temporary workarounds like manual integration installation while troubleshooting

References