> For the complete documentation index, see [llms.txt](https://kb.linknlink.com/isg/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kb.linknlink.com/isg/faq/others/how-to-diagnose-and-fix-home-assistant-startup-issues-via-ssh.md).

# 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.*\
![](/files/4UYS6sr74L9KdkHW3EVt)

#### 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:

```bash
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**

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

**Method 2: View fault logs**

```bash
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:

```bash
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**

```bash
pip uninstall urllib3
pip install urllib3
```

**Verify installation**

```bash
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`