Home Assistant Core — User Guide

1. Quick Start

Home Assistant is an open-source home automation platform that puts local control and privacy first. It runs as a Python application on Linux, macOS, or Windows (WSL), tracking the state of every device in your home and providing a unified web interface, automation engine, and voice assistant integrations to control everything from one place.

Key features:

• Local control — all processing happens on your hardware, no cloud dependency required
• 2,000+ integrations — supports virtually every smart home protocol and device
• Automation engine — trigger-condition-action rules with templates, blueprints, and tracing
• Voice assistant support — Alexa, Google Home, and local Assist pipeline
• WebRTC camera streaming — via built-in go2rtc server
• Multi-user authentication — JWT-based with MFA, groups, and per-entity permissions
• Real-time dashboards — customizable Lovelace UI with live state updates
• Historical data — SQLite-backed recorder with long-term statistics

Prerequisites: Python 3.13+, Linux/macOS/WSL

Install and run:

pip install homeassistant
hass

Home Assistant is starting...
Open the frontend at http://localhost:8123

Tip

The recommended installation method is Home Assistant Operating System (HAOS) on dedicated hardware or a VM. The pip install method above is for Home Assistant Core only — see the Installation section for all options.

What to try next:

• Open the web UI at http://<your-host>:8123 and create your owner account
• Add your first integration via Settings → Devices & Services
• Create an automation via Settings → Automations & Scenes
• See the Admin Guide for architecture details and full configuration reference

2. Installation

System Requirements

Important

Home Assistant does not support native Windows. You must use Windows Subsystem for Linux (WSL) on Windows systems. The --ignore-os-check flag can bypass this validation but is unsupported.

Installation Methods

Home Assistant OS (Recommended)

Download the appropriate image for your hardware from the Home Assistant
installation page. Flash it to an SD card, SSD, or VM disk. Boot and
access the web UI at http://homeassistant.local:8123.

Supported hardware: Raspberry Pi 3/4/5, ODROID, Intel NUC, generic x86-64,
Home Assistant Green, Home Assistant Yellow.

Docker

docker run -d \
  --name homeassistant \
  --privileged \
  --restart=unless-stopped \
  -e TZ=America/New_York \
  -v /path/to/config:/config \
  -v /run/dbus:/run/dbus:ro \
  --network=host \
  ghcr.io/home-assistant/home-assistant:stable

Home Assistant Core (pip)

python3 -m venv homeassistant
source homeassistant/bin/activate
pip install homeassistant
hass

Home Assistant Supervised

Install on a Debian 12 host with the Home Assistant Supervised installer.
Provides the Supervisor add-on system on top of a standard Linux install.

Post-Install Verification

hass --version

2026.5.0

Access the web interface at http://<your-host>:8123. On first launch, you will be guided through onboarding to create the owner account, set your location, and discover devices.

Command-Line Interface

The hass command is the main entry point:

Warning

The --skip-pip flag prevents Home Assistant from installing integration dependencies on startup. Use only in containerized environments where dependencies are pre-installed.

Install Troubleshooting

Error: Home Assistant only supports Linux, OSX and Windows using WSL

Cause: Running on native Windows without WSL.

Solution:

1. Install WSL 2 on Windows
2. Install a Linux distribution (Ubuntu recommended)
3. Run Home Assistant inside the WSL environment

Prevention: Always use WSL on Windows systems.

Error: Home Assistant requires at least Python 3.13.0

Cause: The system Python version is too old.

Solution:

1. Install Python 3.13+ using your package manager or pyenv
2. Create a new virtual environment with the correct Python version

Prevention: Check python3 --version before installing.

Error: Fatal Error: Specified configuration directory does not exist

Cause: The path passed to -c / --config does not exist.

Solution:

1. Create the directory: mkdir -p /path/to/config
2. Or use the default directory by omitting the -c flag

Prevention: Verify the config directory path before starting.

Error: Fatal Error: Unable to create library directory

Cause: Insufficient permissions to create the deps/ subdirectory inside the config directory.

Solution:

1. Ensure the user running hass has write permissions to the config directory
2. Check directory ownership: chown -R $USER:$USER /path/to/config

Prevention: Run Home Assistant as a user with appropriate permissions.

Error: Another instance of Home Assistant is already running

Cause: A lock file indicates another hass process is using this config directory.

Solution:

1. Check for running processes: ps aux | grep hass
2. Stop the existing instance before starting a new one

Prevention: Use a single instance per configuration directory.

Error: ModuleNotFoundError: No module named 'homeassistant'

Cause: The virtual environment is not activated or Home Assistant is not installed.

Solution:

1. Activate your virtual environment: source homeassistant/bin/activate
2. Reinstall: pip install homeassistant

Prevention: Always activate the virtual environment before running hass.

Error: Could not install required packages

Cause: pip cannot resolve or download integration dependencies.

Solution:

1. Check your internet connection
2. Update pip: pip install --upgrade pip
3. If behind a proxy, configure pip proxy settings
4. Use --skip-pip-packages for problematic packages and install them manually

Prevention: Ensure network access and up-to-date pip before starting.

Error: Permission denied: '/config/home-assistant.log'

Cause: The user running Home Assistant does not have write access to the log file.

Solution:

1. Fix permissions: chmod 664 /config/home-assistant.log
2. Or specify a different log file: --log-file /tmp/hass.log

Prevention: Run Home Assistant as a user with write access to the config directory.

Error: Process exits with non-zero code immediately

Cause: Configuration file has syntax errors or a critical integration fails during bootstrap.

Solution:

1. Check the configuration: hass --script check_config
2. Start in recovery mode: hass --recovery-mode
3. Review the log file for detailed error messages

Prevention: Validate configuration before restarting.

Error: Web interface not accessible

Cause: Home Assistant is still starting up, or the HTTP integration failed to bind.

Solution:

1. Wait for the startup to complete (check logs for "Home Assistant initialized")
2. Verify the port is not in use: ss -tlnp | grep 8123
3. Check firewall rules allow port 8123

Prevention: Monitor startup logs and ensure no port conflicts.

3. Configuration

Home Assistant uses YAML configuration files stored in the configuration directory (default: ~/.homeassistant or /config in containers).

Core Configuration File

The primary configuration file is configuration.yaml. A minimal configuration:

homeassistant:
  name: Home
  latitude: 32.87
  longitude: -117.22
  elevation: 430
  unit_system: metric
  currency: USD
  country: US
  time_zone: America/Los_Angeles

default_config:

Tip

The default_config: line enables a curated set of default integrations including the frontend, automation, recorder, history, and device discovery. Most users should keep this enabled.

Core Configuration Options

Supporting Configuration Files

Home Assistant automatically creates and manages several YAML files:

Using Secrets

Store sensitive values in secrets.yaml and reference them with !secret:

# secrets.yaml
mqtt_password: my_secure_password

# configuration.yaml
mqtt:
  broker: 192.168.1.100
  password: !secret mqtt_password

Important

Never commit secrets.yaml to version control. Add it to your .gitignore file.

Configuration Packages

Split large configurations into separate files using packages:

# configuration.yaml
homeassistant:
  packages:
    lighting: !include packages/lighting.yaml
    security: !include packages/security.yaml

Each package file can contain configuration for multiple domains, making it easy to organize by function rather than by integration.

Environment Variables

Validating Configuration

Before restarting, validate your configuration:

hass --script check_config

Testing configuration at /config
Successful config (no errors)

Warning

Always validate configuration before restarting Home Assistant. Invalid YAML or missing required fields will prevent startup or trigger recovery mode.

For the complete configuration reference including all integration options, see the Admin Guide.

4. Core Usage

Managing Integrations

Integrations connect Home Assistant to devices, services, and platforms. Most integrations are configured through the web UI.

Adding an integration:

1. Navigate to Settings → Devices & Services
2. Click Add Integration
3. Search for the integration name
4. Follow the setup wizard (config flow)

Many integrations are discovered automatically via SSDP, Bluetooth, mDNS/Zeroconf, DHCP, and USB protocols. When a compatible device is detected on your network, Home Assistant will prompt you to set it up.

YAML-configured integrations are added directly to configuration.yaml:

sensor:
  - platform: time_date
    display_options:
      - time
      - date

Automations

Automations are the core of home automation — they define rules that trigger actions based on conditions.

Structure: Every automation has three parts:

Creating an automation via the UI:

1. Go to Settings → Automations & Scenes → Create Automation
2. Add triggers (what starts it)
3. Add conditions (optional filters)
4. Add actions (what to do)
5. Save and enable

YAML automation example:

# automations.yaml
- id: "turn_on_porch_light_at_sunset"
  alias: "Turn on porch light at sunset"
  trigger:
    - trigger: sun
      event: sunset
      offset: "-00:30:00"
  condition:
    - condition: state
      entity_id: binary_sensor.someone_home
      state: "on"
  action:
    - action: light.turn_on
      target:
        entity_id: light.porch
      data:
        brightness_pct: 80
  mode: single

Execution modes control behavior when an automation triggers while already running:

Note

Automations fire an automation_triggered event each time they run. Use Settings → Automations → Traces to debug execution history, including which conditions passed or failed.

Scripts

Scripts are reusable sequences of actions that can be called as services. Unlike automations, scripts have no triggers or conditions — they run on demand.

# scripts.yaml
good_morning:
  alias: "Good Morning"
  icon: mdi:weather-sunny
  description: "Morning routine: lights, music, coffee"
  mode: single
  sequence:
    - action: light.turn_on
      target:
        area_id: kitchen
      data:
        brightness_pct: 100
        color_temp_kelvin: 4000
    - action: media_player.play_media
      target:
        entity_id: media_player.kitchen_speaker
      data:
        media_content_id: "morning_playlist"
        media_content_type: "playlist"
    - delay: "00:00:05"
    - action: switch.turn_on
      target:
        entity_id: switch.coffee_maker

Scripts support the same execution modes as automations (single, restart, queued, parallel) and can accept input variables via the fields definition for service call parameters.

Tip

Each script is automatically registered as a service (script.turn_on, script.<script_name>), making it callable from automations, other scripts, or the REST API.

Template Entities

Template entities derive their state from Jinja2 template expressions, allowing you to create virtual sensors, switches, and other entities that combine data from multiple sources.

template:
  - sensor:
      - name: "Average Indoor Temperature"
        unit_of_measurement: "°F"
        state: >
          {{ (states('sensor.living_room_temp') | float +
              states('sensor.bedroom_temp') | float) / 2 | round(1) }}
      - name: "Daylight Hours"
        unit_of_measurement: "hours"
        state: >
          {{ ((as_timestamp(state_attr('sun.sun', 'next_setting')) -
               as_timestamp(state_attr('sun.sun', 'next_rising'))) / 3600)
             | round(1) }}
  - binary_sensor:
      - name: "House Occupied"
        state: >
          {{ states.person | selectattr('state', 'eq', 'home') | list | count > 0 }}

Template entities support all major entity platforms: sensor, binary_sensor, switch, light, cover, fan, lock, number, select, alarm_control_panel, and weather.

Scenes

Scenes capture a snapshot of entity states that can be restored on demand:

# scenes.yaml
- name: "Movie Time"
  entities:
    light.living_room:
      state: "on"
      brightness: 50
      color_temp_kelvin: 2700
    light.ceiling:
      state: "off"
    media_player.tv:
      state: "on"

Dashboards

Home Assistant uses Lovelace as its dashboard system. Dashboards are fully customizable through the UI or YAML and support cards for displaying entity states, controlling devices, and visualizing data.

Common card types include entities, gauge, history-graph, thermostat, media-control, map, weather-forecast, and button cards.

Voice Assistants

Home Assistant integrates with voice assistants for hands-free control:

• Alexa — via the Alexa Smart Home Skill integration (cloud or local emulated Hue)
• Google Home — via Google Assistant integration or emulated Hue
• Assist — Home Assistant's built-in voice assistant pipeline with local speech-to-text and text-to-speech

Note

The Emulated Hue integration (emulated_hue) lets Alexa and Google Home discover and control entities without cloud services. It emulates a Philips Hue bridge on your network (default port 8300) with support for lights, climate, covers, fans, media players, scenes, and scripts.

MQTT

MQTT is a lightweight messaging protocol widely used in IoT. Home Assistant's MQTT integration provides:

• Publish/subscribe to MQTT topics
• Auto-discovery of MQTT devices (prefix: homeassistant)
• Entity platforms for all major domains (sensor, switch, light, climate, etc.)

mqtt:
  broker: 192.168.1.100
  port: 1883
  username: mqtt_user
  password: !secret mqtt_password
  discovery: true
  discovery_prefix: homeassistant

Publishing from an automation:

action:
  - action: mqtt.publish
    data:
      topic: "home/garage/door/set"
      payload: "OPEN"
      qos: 1
      retain: false

Warning

The mqtt.dump service subscribes to a topic and writes all messages to mqtt_dump.txt in the config directory. Use this for debugging only — it can generate large files quickly.

REST API

Home Assistant exposes a REST API for external integrations and scripts. All API calls require a long-lived access token (create one at Profile → Long-Lived Access Tokens).

Check API status:

curl -s -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:8123/api/

{"message": "API running."}

Get all entity states:

curl -s -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:8123/api/states

Set an entity state:

curl -X POST -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"state": "on", "attributes": {"brightness": 200}}' \
  http://localhost:8123/api/states/light.living_room

Call a service:

curl -X POST -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"entity_id": "light.living_room"}' \
  http://localhost:8123/api/services/light/turn_on

Render a template:

curl -X POST -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template": "The sun is {{ states(\"sun.sun\") }}"}' \
  http://localhost:8123/api/template

5. Common Tasks

Set Up Automatic Device Discovery

Goal: Let Home Assistant automatically find devices on your network.

Prerequisites: default_config: in your configuration.yaml (enables SSDP, Zeroconf, DHCP, USB, and Bluetooth discovery).

Steps:

1. Ensure your Home Assistant host is on the same network/VLAN as your devices
2. Navigate to Settings → Devices & Services
3. Check the Discovered section for automatically detected devices
4. Click Configure on a discovered device to set it up

Verify: Discovered devices appear in the Discovered card.

If it fails: Check that multicast traffic (mDNS, SSDP) is not blocked by your router or firewall. Some devices require UPnP to be enabled.

Create a Blueprint-Based Automation

Goal: Use a community-shared automation blueprint to quickly create an automation.

Steps:

1. Go to Settings → Automations & Scenes → Blueprints
2. Click Import Blueprint
3. Paste the blueprint URL
4. Click Preview then Import
5. Click Create Automation on the imported blueprint
6. Fill in the required inputs (entities, values)
7. Save

Verify: The automation appears in your automation list and can be enabled/triggered.

If it fails: Check that all entities referenced in the blueprint inputs exist in your system.

Set Up MQTT Discovery

Goal: Automatically create entities from MQTT devices that publish discovery messages.

Prerequisites: MQTT broker configured and connected.

Steps:

1. Ensure discovery: true in your MQTT config (this is the default)
2. Configure your MQTT device to publish discovery messages to homeassistant/<component>/<node_id>/<object_id>/config
3. The device will appear automatically in Settings → Devices & Services → MQTT

Verify: Entities appear under the MQTT integration and update their state.

If it fails: Use the mqtt.dump service to subscribe to homeassistant/# and verify discovery messages are being received.

Integrate Alexa via Emulated Hue

Goal: Control Home Assistant devices with Alexa without a cloud account.

Steps:

1. Add to configuration.yaml:

   emulated_hue:
     host_ip: 192.168.1.50
     listen_port: 80
     expose_by_default: true
     exposed_domains:
       - switch
       - light
       - media_player
       - fan
     type: alexa
   

2. Restart Home Assistant
3. On your Alexa device, say "Alexa, discover devices"
4. Wait for discovery to complete

Verify: Say "Alexa, turn on [device name]" to test control.

If it fails: Ensure port 80 is available (Alexa requires port 80 for local discovery). Check that the host IP is reachable from the Alexa device.

Warning

Emulated Hue for Alexa requires port 80. If another service is using port 80, you must reconfigure it or use the cloud-based Alexa Smart Home Skill instead.

Back Up and Restore Configuration

Goal: Create a backup of your Home Assistant configuration and restore it if needed.

Steps (backup):

1. Go to Settings → System → Backups
2. Click Create Backup
3. Choose full or partial backup
4. Download the backup file for offsite storage

Steps (restore):

1. Place the backup file (.tar) in the config directory
2. Create a .HA_RESTORE JSON file with:

   {"path": "/config/backup.tar", "password": null, "remove_after_restore": true, "restore_database": true, "restore_homeassistant": true}
   

3. Restart Home Assistant — it will detect the restore instruction and process it before boot

Verify: Home Assistant starts with the restored configuration.

If it fails: Check .HA_RESTORE_RESULT for error details. The restore instruction file is always removed after processing to prevent boot loops.

Set Up Camera Streaming with go2rtc

Goal: Enable WebRTC streaming for camera entities.

Prerequisites: go2rtc integration (included by default with default_config:).

Steps:

1. The go2rtc server starts automatically when Home Assistant boots
2. Camera integrations that support streaming will automatically register their streams with go2rtc
3. Open a camera entity card in your dashboard — it will use WebRTC streaming by default

Verify: Camera feeds show low-latency video in the dashboard.

If it fails: Check that the go2rtc server is running (look for go2rtc in the logs). Ensure your browser supports WebRTC.

Set Up Multi-Factor Authentication

Goal: Add an extra layer of security to user accounts.

Steps:

1. Go to Profile (click your user icon in the sidebar)
2. Under Multi-factor Authentication Modules, enable a module
3. Follow the setup wizard to configure your MFA device (e.g., TOTP authenticator app)
4. Scan the QR code with your authenticator app
5. Enter the verification code to confirm

Verify: On next login, you will be prompted for both password and MFA code.

Important

MFA sessions expire after 5 minutes. System-generated users (like the Supervisor user) cannot enable MFA.

Set Up the MCP Server for AI Integration

Goal: Expose Home Assistant to AI/LLM tools via the Model Context Protocol.

Steps:

1. Go to Settings → Devices & Services → Add Integration
2. Search for Model Context Protocol Server
3. Select which LLM APIs to expose (default: Assist)
4. The MCP server endpoints become available at:
   • Streamable HTTP: POST /api/mcp
   • SSE (legacy): GET /mcp_server/sse

Verify: Connect an MCP-compatible AI tool to the endpoint with a valid access token.

Monitor Startup Performance

Goal: Identify slow integrations that delay startup.

Steps:

1. Start Home Assistant with verbose logging: hass --verbose
2. Watch the logs for the startup watchdog messages (logged every 60 seconds during slow startups)
3. Check Settings → System → Logs after startup completes

Startup is divided into stages:

• Stage 0: Core infrastructure (logging, HTTP, frontend, recorder) — immediate
• Stage 1: Discovery services (Bluetooth, DHCP, SSDP, USB, cloud) — 120s timeout
• Stage 2: All user integrations — 300s timeout

If it fails: Integrations that exceed their stage timeout are loaded in the background. Check logs for Setup of integration X is taking over X seconds.

Create a Configuration Package

Goal: Organize related configuration into a single file.

Steps:

1. Create a packages/ directory in your config folder
2. Create a package file, e.g., packages/garage.yaml:

   sensor:
     - platform: template
       sensors:
         garage_status:
           friendly_name: "Garage Status"
           value_template: "{{ states('cover.garage_door') }}"
   
   automation:
     - alias: "Close garage at night"
       trigger:
         - trigger: time
           at: "22:00:00"
       action:
         - action: cover.close_cover
           target:
             entity_id: cover.garage_door
   

3. Reference it in configuration.yaml:

   homeassistant:
     packages:
       garage: !include packages/garage.yaml
   

4. Validate and restart

Verify: Entities and automations from the package appear in the UI.

Set Up External Access

Goal: Access Home Assistant securely from outside your local network.

Steps:

1. Set your internal and external URLs in configuration.yaml:

   homeassistant:
     internal_url: "http://homeassistant.local:8123"
     external_url: "https://home.example.com"
   

2. Configure port forwarding on your router (port 8123) or use a reverse proxy (Nginx, Traefik)
3. Set up SSL/TLS certificates for HTTPS
4. Restart Home Assistant

Verify: Access your instance from outside your network using the external URL.

Caution

Never expose Home Assistant over the internet without HTTPS. Use strong passwords, enable MFA, and consider using Home Assistant Cloud (Nabu Casa) for a secure, zero-configuration remote access solution.

6. Troubleshooting

Diagnostic Decision Tree

Problem?
├── Can't access web UI
│   ├── Check if HA is running: ps aux | grep hass
│   ├── Check port: ss -tlnp | grep 8123
│   └── Check logs: tail -f CONFIG/home-assistant.log
├── Integration not loading
│   ├── Check Settings → System → Logs for errors
│   ├── Validate config: hass --script check_config
│   └── Try recovery mode: hass --recovery-mode
├── Automation not triggering
│   ├── Check automation is enabled
│   ├── Check automation traces for condition failures
│   └── Verify entity states match trigger conditions
├── Device not discovered
│   ├── Verify device is on the same network/VLAN
│   ├── Check that mDNS/SSDP/UPnP is not blocked
│   └── Try manual integration setup
└── Performance issues
    ├── Check recorder database size
    ├── Review integration count and polling intervals
    └── Check CPU/memory: Settings → System → Hardware

Error: ConfigEntryError: Invalid credentials

Cause: Integration credentials (username, password, API key) are incorrect or expired.

Solution:

1. Go to Settings → Devices & Services
2. Find the affected integration
3. Click Reconfigure or Re-authenticate
4. Enter the correct credentials

Prevention: Use secrets.yaml for credentials and update them when they change.

Error: ConfigEntryNotReady: Error during setup

Cause: The device or service required by the integration is temporarily unavailable.

Solution:

1. Verify the device/service is online and reachable
2. Check network connectivity between Home Assistant and the device
3. Home Assistant will automatically retry setup at increasing intervals

Prevention: Ensure devices have static IP addresses or reliable DHCP reservations.

Error: The go2rtc server version is not supported

Cause: An external go2rtc instance is running an incompatible version.

Solution:

1. Update go2rtc to the recommended version (1.9.14 or later)
2. Or remove the external URL to use the built-in go2rtc server

Prevention: Keep external go2rtc installations updated alongside Home Assistant.

Error: Camera has no stream source

Cause: The camera integration does not provide a streaming URL for go2rtc.

Solution:

1. Check if the camera integration supports streaming
2. Verify the camera is online and accessible
3. Some cameras require RTSP to be enabled in their settings

Prevention: Confirm camera streaming compatibility before purchase.

Error: Unknown auth provider

Cause: The authentication configuration references a provider that is not loaded.

Solution:

1. Check configuration.yaml for auth_providers: configuration
2. Ensure the referenced provider type is valid
3. Remove or correct invalid provider references

Prevention: Use the default auth provider configuration unless you have specific needs.

Error: Credential is already linked to a user

Cause: Attempting to link login credentials that are already associated with another user account.

Solution:

1. Use different credentials for the new user
2. Or unlink the credentials from the existing user first

Prevention: Each set of credentials can only be linked to one user.

Error: Value cannot be None (in automation/script configuration)

Cause: A required field in the automation or script configuration is missing.

Solution:

1. Check the automation/script YAML for missing required fields
2. Validate configuration: hass --script check_config
3. Common missing fields: trigger type, action service, entity_id

Prevention: Use the UI editor for automations and scripts to ensure all required fields are populated.

Error: Duplicate X10 device / Duplicate override (Insteon)

Cause: The Insteon configuration contains duplicate device entries.

Solution:

1. Review Insteon device configuration for duplicates
2. Remove the duplicate entry
3. Restart Home Assistant

Prevention: Check for existing entries before adding new Insteon device overrides.

Error: Not a valid app slug (Supervisor)

Cause: An invalid add-on identifier was passed to a Supervisor service call.

Solution:

1. Verify the add-on slug matches an installed add-on
2. List available add-ons via Settings → Add-ons
3. Use the correct slug format (e.g., core_mosquitto)

Prevention: Copy add-on slugs from the Supervisor UI rather than typing them manually.

Error: Cannot create a backup with database but without Home Assistant

Cause: Attempting to create a backup that includes the database but excludes the Home Assistant configuration.

Solution:

1. Include both Home Assistant and database in the backup
2. Or exclude the database if you only need configuration

Prevention: The database depends on the Home Assistant configuration; always back them up together.

Error: Error updating Home Assistant Core/OS/Supervisor

Cause: The update process failed, typically due to network issues or insufficient storage.

Solution:

1. Check internet connectivity
2. Ensure sufficient disk space (at least 1 GB free)
3. Check Supervisor logs for detailed error messages
4. Retry the update

Prevention: Maintain adequate free disk space and stable network connectivity.

Error: Recovery mode activates on startup

Cause: Configuration parsing failed, core setup failed, or a critical integration (like the frontend) failed to load.

Solution:

1. In recovery mode, only essential integrations are loaded
2. Access the web UI and check Settings → System → Logs for the root cause
3. Fix the configuration issue
4. Disable safe mode via the UI or delete the .safe_mode file from your config directory
5. Restart normally

Prevention: Always validate configuration changes before restarting.

Warning

Recovery mode starts with minimal integrations. Your devices and automations will not be available until you fix the underlying issue and restart normally.

Error: Backup failed: no backup_id

Cause: The backup creation process failed to generate a valid backup identifier.

Solution:

1. Check available disk space
2. Review Supervisor logs for the underlying error
3. Retry the backup

Prevention: Ensure sufficient disk space before creating backups.

Slow Startup Debugging

Cause: Integrations taking too long to initialize, often due to unreachable devices or slow network responses.

Solution:

1. Start with verbose logging: hass --verbose
2. Watch for "Setup of integration X is taking over Y seconds" messages
3. Identify integrations with slow or failing network connections
4. Consider removing or disabling problematic integrations temporarily
5. Check that local DNS resolution is working properly

Prevention: Use static IP addresses for critical devices. Ensure reliable network infrastructure.

7. FAQ

General

Q: What is the difference between Home Assistant OS, Supervised, Container, and Core?

Home Assistant OS is the recommended all-in-one operating system image. Supervised installs the Supervisor on Debian Linux. Container runs Home Assistant in Docker without the Supervisor. Core is a bare Python virtual environment install without Supervisor or add-on support. All four run the same Home Assistant Core code — the difference is the management layer around it.

Q: What Python version does Home Assistant require?

Python 3.13 or higher. The exact minimum is defined in homeassistant.const.REQUIRED_PYTHON_VER.

Q: Can I run Home Assistant on Windows?

Only via Windows Subsystem for Linux (WSL). Native Windows is not supported. You can bypass the OS check with --ignore-os-check but this is unsupported.

Q: Where are my configuration files stored?

By default in ~/.homeassistant/ (Core install) or /config/ (container/HAOS). You can specify a custom path with the -c / --config flag.

Configuration

Q: What does default_config: do?

It enables a curated set of ~50 default integrations that most users want, including the frontend, automation engine, history, logbook, recorder, device discovery (SSDP, Zeroconf, DHCP, USB, Bluetooth), cloud connectivity, and more.

Q: How do I split my configuration into multiple files?

Use !include directives in configuration.yaml or the packages system. Packages are more flexible as they allow mixing multiple domains in a single file.

Q: How do I check my configuration for errors?

Run hass --script check_config from the command line, or use Developer Tools → YAML → Check Configuration in the web UI.

Automations & Scripts

Q: What is the difference between automations and scripts?

Automations have triggers and conditions — they run automatically when conditions are met. Scripts are just action sequences — they only run when explicitly called as a service.

Q: What are automation execution modes?

single (default) ignores new triggers while running. restart cancels the current run and starts over. queued queues new triggers. parallel runs multiple instances simultaneously. Set via the mode key.

Q: Can I use blueprints for scripts?

Yes. Both automations and scripts support blueprints. Import blueprint URLs via the UI at Settings → Automations & Scenes → Blueprints.

Q: How do I pass variables to a script?

Define fields in the script configuration for UI support, then pass variables when calling the script.turn_on or script.<name> service.

Integrations

Q: How does automatic device discovery work?

Home Assistant uses multiple discovery protocols: SSDP (UPnP devices), Zeroconf/mDNS (Apple/network devices), DHCP (MAC address matching), USB (device enumeration), and Bluetooth (BLE advertisements). Each integration registers matchers for these protocols, and when a match is found, a config flow is initiated.

Q: How do I configure MQTT discovery?

MQTT discovery is enabled by default (prefix: homeassistant). Devices publish a JSON config message to homeassistant/<component>/<node_id>/<object_id>/config. Home Assistant automatically creates the corresponding entities.

Q: Can I use an external MQTT broker?

Yes. Configure the broker address, port, and credentials in the MQTT integration config entry or YAML. Home Assistant supports TCP and WebSocket transports, TLS encryption, and client certificates.

Authentication

Q: How do access tokens work?

Home Assistant uses JWT (JSON Web Token) authentication. Refresh tokens last 90 days and generate short-lived access tokens (30-minute expiry). Long-lived access tokens can be created in your user profile for API access and do not expire automatically.

Q: What are the default user groups?

Three groups exist by default: Administrators (full access), Users (standard entity access), and Read Only (view-only access). The owner account is always in the Administrators group and cannot be deactivated.

Q: What is recovery mode?

Recovery mode starts Home Assistant with only essential integrations loaded. It activates automatically when configuration parsing fails or a critical integration (like the frontend) fails to load. You can also start it manually with hass --recovery-mode.

Performance

Q: How do I reduce startup time?

Identify slow integrations via verbose logging. Ensure devices have static IPs. Reduce the number of polling-based integrations. Use an SSD for the config directory and recorder database.

Q: How do I manage the recorder database size?

Configure the recorder integration to exclude entities, domains, or event types you do not need. Set a purge_keep_days value to automatically remove old data. The recorder uses SQLite in WAL mode by default.