Home Assistant Not Starting? How to Diagnose and Fix Common Issues

There's nothing quite like the sinking feeling of checking your phone and realizing your entire smart home is offline because Home Assistant won't start. Your lights don't respond, automations are dead, and the dashboard just spins. I've been running Home Assistant for over four years — across a Raspberry Pi 3, a Pi 4, a Home Assistant Green, and now a VM on a mini PC — and I've dealt with every startup failure imaginable. Here's how to diagnose and fix each one, organized by installation type.

If your HA was working fine yesterday, the most common causes are (in order of likelihood): a failed or interrupted update, database corruption, disk space exhaustion, or a broken custom integration. Keep those in mind as we work through the specifics.

Emergency Access: Reading Logs When the UI Won't Load

The first step in any startup failure is reading the logs. But if the web UI isn't loading, how do you access them?

Home Assistant OS (Green, Yellow, RPi)

• SSH: If you have the SSH & Web Terminal add-on installed (and you should — install it now while things are working), connect via ssh [email protected] -p 22222. Then run ha core logs for Core logs or ha supervisor logs for Supervisor logs.
• Direct console: Connect a keyboard and monitor via HDMI. On the Green, use the HDMI port on the back. Log in as root (no password on HAOS) and run ha core logs.
• Serial console (Yellow): The Yellow has a serial debug port via USB-C. Connect to a computer and use a serial terminal at 115200 baud.

Home Assistant Container (Docker)

• SSH into your Docker host: docker logs homeassistant --tail 100 (replace "homeassistant" with your container name). Add -f to follow logs in real time. If the container isn't starting, docker ps -a shows its status: "Restarting" means crash-looping, "Exited" means it started and failed.

Home Assistant Core (venv)

• Check ~/.homeassistant/home-assistant.log directly. Or start manually from the terminal: hass -c /path/to/config -v and watch the console output for errors.

Safe Mode: Your Best Friend

Home Assistant's safe mode starts the core system with all custom integrations and custom Lovelace configurations disabled. If the problem is a broken custom component from HACS, safe mode gets you back to a working UI so you can remove or fix the offender.

• HAOS/Supervised: Via SSH, run ha core restart --safe-mode.
• Docker: Rename the custom_components folder: mv custom_components custom_components_bak and restart the container.
• Core (venv): Same approach — rename custom_components and restart hass.

If HA starts in safe mode, you know a custom integration is the problem. Re-enable them one at a time to identify which one is crashing the system.

HAOS / Green / Yellow: Common Issues

Boot Loop (Device Keeps Restarting)

LED codes on the Green: Solid yellow means booting. Solid green means running. Blinking yellow for more than 5 minutes means the OS loaded but Core is crashing. LED stays off means no power or hardware failure.

Steps to fix: First, wait at least 10 minutes — HAOS sometimes runs database migrations or file system checks during boot that take a long time, and interrupting makes things worse. Connect a monitor via HDMI to watch for error messages. If Core is crashing, try safe mode from the console: ha core restart --safe-mode. If the OS itself won't boot, you may need to re-flash HAOS to the eMMC — your data partition may survive the re-flash.

Failed Update

A power loss or network timeout during an update leaves a mix of old and new files. This is one of the most common causes of startup failure. Via SSH: check the running version with ha core info. Try restarting Core: ha core restart. If that doesn't work, force a clean re-download: ha core update --version=XXXX.XX.X (specify the target version). If the Supervisor is broken: ha supervisor repair then ha supervisor restart. Nuclear option: ha backups restore SLUG_NAME.

Corrupt SD Card or eMMC

If you're running HAOS on a Raspberry Pi with an SD card, storage corruption is a matter of when, not if. SD cards aren't designed for the constant small writes that a database-heavy application generates. Symptoms: random file system errors, databases that won't open, boot failures after months of working fine.

Prevention: Migrate to a USB SSD. A $25 128GB USB SSD will outlast any SD card by years and is dramatically faster. The Pi 4 boots from USB natively. The Yellow supports an NVMe SSD upgrade. Recovery: Flash fresh HAOS onto a new drive, boot, and restore from backup. This is why automated backups are non-negotiable.

Docker: Common Issues

Port Conflicts

Something grabbed port 8123 before HA could. Run sudo lsof -i :8123 (Linux/Mac) to find the culprit. Fix: stop the conflicting process, or change HA's port mapping in docker-compose.yml to "8124:8123" and access HA on port 8124.

Permission Errors

"Permission denied" in container logs means the user inside the container doesn't own the config files on the host. This happens when you edit files as a different user. Fix: sudo chown -R root:root /path/to/ha-config.

Volume Mount Problems

Seeing "FileNotFoundError: configuration.yaml"? Your volume mount isn't working. Verify with docker exec homeassistant ls /config/ — if the directory is empty, the mount failed. Check your docker-compose.yml for correct paths (a common mistake is relative paths that resolve differently than expected).

Supervised: Dependency Breaks

The Supervised installation depends on specific versions of Docker, NetworkManager, and other OS packages. When your host OS updates these, the Supervisor can break. Check the official HA docs for supported Docker versions, downgrade if needed: apt install docker-ce=VERSION_STRING, then systemctl restart hassio-supervisor.

Long-term, consider migrating to HAOS on a dedicated device or to a Container installation — Supervised is powerful but high-maintenance and the most fragile installation type.

Core (venv): Python Issues

After a system Python update (e.g., 3.11 to 3.12), the venv may reference the old Python binary and refuse to start. Fix: back up your config directory (it's separate from the venv), delete the old venv, create a new one with the current Python: python3 -m venv /path/to/ha-venv, activate and install: pip install homeassistant, then start pointing at your existing config.

For pip dependency conflicts, a fresh venv is almost always cleaner than trying to manually resolve version conflicts. Don't go down that rabbit hole.

Issues Common to All Installation Types

Database Corruption (home-assistant_v2.db)

HA stores all historical data in a SQLite database that can corrupt from sudden power loss, full disk, or SD card degradation. On active systems, this database can reach 1-5 GB. Symptoms: extremely slow startup, "database is locked" or "database disk image is malformed" errors.

Quick fix: Stop HA. Rename (don't delete) the database and WAL file: mv home-assistant_v2.db home-assistant_v2.db.corrupt and mv home-assistant_v2.db-wal home-assistant_v2.db-wal.corrupt. Start HA — it creates a fresh database instantly. You'll lose history data, but automations, devices, and entities are stored in config files and are completely unaffected.

Prevention: Set recorder: purge_keep_days: 10 in configuration.yaml to auto-delete old history. Exclude high-frequency entities that generate excessive data. For serious setups, use MariaDB or PostgreSQL instead of SQLite — external databases handle concurrent writes better and are far more resistant to corruption.

Integration Errors Blocking Startup

Custom integrations from HACS can block startup if they hang during initialization (e.g., trying to reach an offline device) or have breaking changes after an update. Check logs for ERROR or CRITICAL entries — the integration name is usually included. Start in safe mode to confirm. To remove without the UI: move the integration folder out of custom_components/.

Out of Disk Space

The database, log files, and backup snapshots can silently fill a small disk (especially 8-16 GB SD cards). Check with df -h. Quick cleanup: delete old backups (ha backups to list, keep two most recent), delete the database (HA recreates it), and check the log file size — if home-assistant.log is hundreds of MB, an integration is spamming errors. Fix the underlying error after HA starts.

DNS Resolution Failures

Cloud integrations (weather, HACS, Nabu Casa) hang during startup if DNS is broken. Test from the host with nslookup google.com. Fix: set a static DNS server like 1.1.1.1 (Cloudflare) or 8.8.8.8 (Google) in HAOS network settings, in docker-compose.yml via the dns: directive, or in /etc/resolv.conf for venv installs.

Z-Wave/Zigbee USB Stick Not Detected

USB device paths can change after a reboot (e.g., /dev/ttyUSB0 becomes /dev/ttyUSB1). For Docker, use the stable by-id path: run ls /dev/serial/by-id/ to find your device's persistent path and use that in docker-compose.yml instead of /dev/ttyUSB0. For VMs (Proxmox), configure USB passthrough using vendor/product ID, not port number. For bare metal, try a USB 2.0 port — USB 3.0 ports generate radio interference that disrupts Zigbee/Z-Wave signals. A short USB extension cable can also help.

Restoring From Backup

HAOS: If the Supervisor is running: ha backups restore SLUG --homeassistant (restores just Core, faster) or ha backups restore SLUG (restores everything). If nothing is running: flash fresh HAOS, boot, and select "Restore from backup" during onboarding.

Docker/Core: Stop HA, replace your config directory contents with the backup, start HA. The backup is a tar.gz containing the full config directory.

Prevention: Set Up While Things Are Working

Don't wait for a failure to prepare for one:

• Automated backups: Install the Google Drive Backup add-on (HAOS) or set up a cron job to copy backups to a NAS or cloud. Back up daily, keep at least 7 days.
• SSH access: Install the SSH & Web Terminal add-on now. You need out-of-band access when the UI is down.
• UPS: A $40 UPS prevents the most common cause of database corruption — sudden power loss. Connect your HA device, router, and critical hubs.
• Move off SD cards: Migrate to a USB SSD. $25 eliminates the most common hardware failure point.
• Recorder limits: Set purge_keep_days to 10-14 days to prevent database bloat.
• Pin HACS versions: Don't auto-update custom integrations. Update manually, one at a time, after checking changelogs for breaking changes. A bad custom integration update is the most common cause of "HA was working yesterday, now it won't start."

A properly configured Home Assistant instance on stable hardware with automated backups should run for months between issues. Most of the problems in this article are preventable — and the ones that aren't are recoverable if you've prepared.