How to Diagnose and Fix Home Assistant Startup Issues via SSH

When Home Assistant (HA) encounters issues such as failure to start, frequent crashes, or not starting automatically after reboot, the most common causes include:

• Broken or conflicting Python dependencies introduced by HACS

• Incompatible third-party (custom) integrations

• System resource issues (high memory usage, blocked processes, etc.)

Why Self-Diagnosis Is Necessary

1️⃣ HACS Comes with Known Risks

Home Assistant Logs warns users that installing HACS and custom integrations involves risk. These warnings are clearly shown in both the HA UI and system logs.

WARNING (SyncWorker_0) [homeassistant.loader] We found a custom integration xxx which has not been tested by Home Assistant. This component might cause stability problems.

2️⃣ Not All HACS Integrations Can Be Fully Tested

While we have tested many popular HACS integrations, it is not possible to guarantee full compatibility for all of them.

Therefore, when HA behaves abnormally, 👉 SSH-based diagnosis is currently the most direct and effective troubleshooting method.

How to Log In via SSH：

Step 1: Open a Command-Line Tool

• Windows: CMD or PowerShell

• macOS / Linux: Terminal

Step 2: Connect to the ISG via SSH

Run the following command:

ssh -p 8022 linknlink@127.0.0.1

Notes:

• Replace 127.0.0.1 with your ISG device IP address if needed

• 8022 is the SSH port

Step 3: Enter the Password

• Default SSH password: linknlink123

• For security reasons, you can change it here: ISG → Settings → System → Access Password

How to Start Diagnosing the Issue

1. Check Home Assistant Logs

Method 1: View recent logs

tail -n 100 "$LLOGDIR/hass/current"

Method 2: View fault logs

cat $UBTDIR/root/.homeassistant/home-assistant.log.fault

---

2. Analyze Logs with an AI Tool (Recommended)

1. Copy the log output

2. Paste it into ChatGPT or another AI tool

3. Clearly describe:

   • Your runtime environment: Ubuntu running under Termux + proot

   • The issue you are facing (e.g. HA fails to start)

AI tools can often quickly identify:

• Missing Python packages

• Dependency conflicts

• Root causes of startup failures

---

3. Enter the Home Assistant Runtime Environment

Execute the following commands in SSH:

proot-distro login ubuntu
source ~/homeassistant/bin/activate

Explanation:

• The first command enters the Ubuntu container

• The second activates HA’s Python virtual environment

---

4. Fix Dependencies Based on Diagnosis (Example)

Example: Fixing an urllib3 dependency issue

pip uninstall urllib3
pip install urllib3

Verify installation

pip show urllib3

If version information is displayed, the dependency has been restored successfully.

Notes & Best Practices

• HA crashes are not necessarily hardware-related

• Most issues are caused by dependency conflicts or third-party integrations

• Frequent HACS installs or updates increase the risk of conflicts

• Recording the exact time of crashes or restarts greatly helps log analysis

• We are continuously improving the Dependency Check feature to cover more packages, including urllib3