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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://kb.linknlink.com/isg/faq/others/how-to-diagnose-and-fix-home-assistant-startup-issues-via-ssh.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.