Home Assistant Guide

Simple tutorials for powerful automations

Trouble Accessing Home Assistant

Access problems in Home Assistant usually fall into three categories: the system does not start, you are locked out (forgotten credentials), or remote access through Nabu Casa fails. The following sections explain how to recover in each situation.

Home Assistant Will Not Start

If Home Assistant fails to start, the web interface and add-ons will not load. You will need to access the device directly through its console or an SSH connection to the host.

  • Home Assistant Green: Connect a monitor and keyboard to the HDMI and USB ports. When powered on, press Enter to access the command prompt.
  • Home Assistant Yellow: The Yellow model is headless and does not output video over HDMI. To access its console, use the USB-C serial connection following the official instructions at yellow.home-assistant.io.
  • Raspberry Pi or other hardware: Connect a keyboard and HDMI display. If no image appears, restart the device with the monitor attached.
  • Virtual machine: Use the "Console" or "Terminal" view in your virtualization software (for example, Proxmox or VirtualBox).

Once the ha > prompt appears, the following commands can help diagnose startup problems: 

ha core check        # Validate configuration
ha core logs         # View error messages
df -h                # Check available disk space

If configuration errors are reported, correct them and restart Home Assistant. You can restore a previous backup if needed: 

ha backups list
ha backups restore slugname

Locked Out or Forgot Password

If you cannot log in because you forgot your username or password, you can recover access through the system console. The SSH & Terminal add-on cannot be used until Home Assistant is running.

Recovering Your Username

To view all registered accounts, enter: 

ha auth list

Identify your user account from the list before resetting the password.

Resetting a Password

Once you know the username, reset the password using: 

ha auth reset --username yourusername --password newpassword

Replace yourusername and newpassword with your details. You can now sign in with the new password.

If "Command Not Found" Appears

This message indicates the command was entered inside an add-on terminal rather than the system console. Ensure you are connected directly to the device or VM console.

For Docker Installations

On a Docker host, reset passwords using: 

docker exec -it homeassistant bash
hass --script auth --config /config change_password existing_user new_password
exit
docker restart homeassistant

When the Owner Account Cannot Be Recovered

If the owner account cannot be reset, recovery can only be done by restoring a backup or performing a factory reset.

  • Restore a backup: Use a snapshot that includes a valid administrator account.
  • Reset the device: Perform a hardware reset (for example, following the instructions for Home Assistant Green or Yellow). This erases all existing data and begins a new setup.

Recovering Configuration and Data

Unless the storage device is corrupted, your configuration and backup files remain on the system.

  • Using the console: Log in as root (no password). Useful commands include: 
    core logs        # Core logs
supervisor logs  # Supervisor logs
host reboot      # Reboot system
  • Accessing storage directly: Remove the SD card or drive and connect it to another computer. Files are located in the hassos-data partition under: 
    /mnt/data/supervisor
    On Linux this can be opened natively; on Windows use DiskInternals Linux Reader; on macOS use macFUSE.

Trouble with Remote Access (Nabu Casa)

If Home Assistant Cloud remote access stops working, the issue may relate to user permissions, SSL certificate generation, or temporary connectivity problems.

Check Local Access

Verify User Permissions

If one person cannot connect remotely while others can, that account may be limited to local logins. To allow remote access:

  1. Go to Settings → People.
  2. Select the affected person.
  3. Ensure Allow person to log in is enabled.
  4. Disable Can only log in from the local network.

Resolving SSL or Certificate Errors

If the Nabu Casa remote URL does not load, shows an SSL warning, or displays the error:

Unable to connect to Home Assistant
Encountered error: Failed to perform SSL handshake, please ensure your certificate is valid.

This usually indicates a problem with SSL certificate validation or incorrect system time. Try the following steps:

  • Wait several minutes - new certificates can take time to generate.
  • Check that both your Home Assistant device and your phone/computer have the correct date and time. An incorrect clock can cause SSL handshakes to fail.
  • Check your network connection for general issues.
  • Visit test-ipv6.com to check IPv6. Follow any recommendations given.

If IPv6 appears to be the cause, disable it in Home Assistant:

  1. Go to Settings → System → Network.
  2. Expand the IPv6 section and select Disabled.
  3. Save changes, then restart Home Assistant under Settings → System → Restart Home Assistant → Expand Advanced Options → Reboot system.

To have all network settings applied from scratch, you can also reboot the host entirely:

  1. Go to Settings → System → Restart Home Assistant (power icon at top right).
  2. Expand Advanced Options.
  3. Select Reboot system.

Resetting Cloud Data

If SSL or connection issues persist:

  1. Open Settings → Home Assistant Cloud.
  2. Select the three dots (⋮) → Reset cloud data.
  3. Restart Home Assistant and log back into your Nabu Casa account.
  4. Wait several minutes while a new certificate is requested and applied.

Checking for Outages

To see whether the issue is due to a service outage, visit the official Home Assistant Status Page. At the top, you'll see the current system status (for example, "All Systems Operational"). Scroll down to the Home Assistant Cloud or Remote UI section to check if any outages or degraded performance are reported.

If there is a Major Outage or Partial Outage listed, the issue is likely on the server side. If all systems show as operational, focus on your local network, clock, or SSL configuration. The page also provides a history of past incidents for reference.

If remote access remains unavailable, local network access or a VPN (for example, Tailscale or WireGuard) can provide a secure alternative connection.

Summary

  • System not starting: Check configuration and logs from the console.
  • Forgotten credentials: Use ha auth list and ha auth reset from the console.
  • Remote access issues: Verify permissions, check date/time, test IPv6, and reset cloud data only once if necessary.
  • Data recovery: Access configuration directly through the console or by mounting the storage externally.

Most access issues can be resolved without reinstalling Home Assistant. A factory reset should only be used when other recovery options have been exhausted.