Troubleshooting.

How to use this page.

The page is organized as a reference. Readers jump to the recipe that matches the current problem; sequential reading is not required.

Identify the problem shape first. Most troubleshooting starts with a vague symptom ("things are not working right"). Before diving into a recipe, spend a moment on precisely what is happening — which zone, which automation, what error, what changed recently. Precision about the symptom narrows which recipe applies.

The general diagnostic approach applies to every recipe. Each recipe below follows the same structure, but underneath is a consistent method: establish the symptom precisely, gather the available evidence (logs, traces, state history), check the simplest likely causes first, work toward less-likely causes, and verify the fix by reproducing the original triggering conditions.

Avoid changing multiple things at once. A single change at a time makes it clear which change fixed (or broke) the situation. Changing three things simultaneously and observing improvement leaves uncertainty about which change mattered.

Document what you find. Problems recur, sometimes years later, sometimes across different operations in the collective. Notes about what the symptom was, what the cause turned out to be, and what the fix was feed back into the Troubleshooting page and the collective's shared knowledge. A short log entry per significant troubleshooting session is cheap and valuable.

Use the official resources. The official Home Assistant help pages and the community forum cover problems the collective's experience does not. The forum especially is a useful place for current issues — the community is active, and a specific error message often produces useful search results.

The recipe format.

Every recipe follows the same structure.

Symptom. What the grower observes. Specific enough to be recognizable; general enough to match variations of the same underlying problem.

First check. The simplest thing to verify before deeper investigation. A non-trivial share of problems resolve at this step; the recipe catches them before diving deeper.

Diagnostic steps. The investigation sequence, from simplest to most complex. Each step narrows the possible causes.

Common causes. The patterns that produce the symptom, in rough order of frequency.

Resolution paths. What to do for each identified cause.

Prevention. When known, the practice that prevents the problem from recurring.

See also. Links to related recipes and relevant pages elsewhere in the section.

Before starting troubleshooting.

Prerequisites that apply across recipes.

The Home Assistant log is available. Settings → System → Logs shows recent errors, warnings, and info-level messages. Many problems surface here; starting with the log is almost always the right first step.

The trace viewer works. For automation issues, the trace viewer shows what happened during each run. Accessing it requires knowing which automation to check; the trace for the automation that should have acted is the primary evidence.

The Developer Tools are accessible. Settings → Developer Tools includes tools for state inspection, service calls, template testing, and event monitoring. These are the workshop for investigating state and behavior.

A recent backup exists. Troubleshooting sometimes involves changes that do not go well. A backup from before the troubleshooting session lets the grower revert if a fix makes things worse. Never begin invasive troubleshooting without a recent backup.

An understanding of what changed recently. A problem that appeared today probably correlates with something that changed recently — a Home Assistant update, an integration change, a hardware change, a configuration edit. The change log is often the fastest path to the cause.

Recipe: The integration that stopped working after an update.

Symptom. After a Home Assistant update, a specific integration that was working is now showing errors, reporting entities as unavailable, or failing to load. Other integrations are fine.

First check. Look at the Home Assistant log (Settings → System → Logs) for errors mentioning the integration's name. The log usually names the specific problem.

Diagnostic steps.

1. Check the Home Assistant release notes for the version that was just installed. Integration breaking changes are listed; the integration may be mentioned. 2. Check the integration's own release notes if it is a custom integration (HACS). 3. Check the integration's Home Assistant documentation for any configuration changes required by the new version. 4. Try reloading the integration from Settings → Devices & Services — the integration's three-dot menu includes "Reload." 5. Try removing and re-adding the integration (after confirming a backup exists). 6. Check the community forum or GitHub issues for the integration — others may have reported the same problem.

Common causes.

- Breaking changes in Home Assistant core that affect the integration. The release notes warn about these; sometimes the fix is a configuration adjustment. - Integration-side breakage from API changes at the service provider. Cloud integrations depend on external services whose APIs change. - Custom integration not updated for the new Home Assistant version. Community integrations update on their own schedules; a Home Assistant update sometimes outpaces a specific custom integration. - Configuration incompatibility. A configuration option that worked previously may have been deprecated; the new version does not accept it.

Resolution paths.

- Follow the release notes' guidance. If the breaking change is documented, the fix is usually named. - Update the custom integration to a version compatible with the current Home Assistant. HACS shows available updates; installing the matching version typically resolves the issue. - Adjust the configuration to match the current syntax. Error messages often indicate the specific configuration issue. - If no immediate fix is available, rollback Home Assistant to the previous version. Temporary rollback preserves operation while waiting for a proper fix.

Prevention. Stage updates on a test system first where possible. For operations where that is not practical, read release notes before updating; back up before every update so rollback is available.

See also. [Updates and Version Management](/home-assistant/operations/updates) for the update discipline that reduces surprise breakage. [Backup and Recovery](/home-assistant/operations/backup) for the rollback capability.

Recipe: The sensor that went silent.

Symptom. A specific sensor is showing as "unavailable" or is not updating. Its historical data stops at a specific time; no new readings are arriving.

First check. Is the device itself still working? Physical check — is it powered, is it connected, does it show any indicator lights? For battery-powered devices, is the battery level reasonable (or reported at all)?

Diagnostic steps.

1. Determine which integration the sensor comes through. Settings → Devices & Services shows the integration; the device page shows the sensor's details. 2. Check whether the integration as a whole is healthy or whether only this specific sensor is affected. If the whole integration is failing, treat it as "integration down" rather than "single sensor" (different recipe). 3. For battery-powered sensors: check the battery level (if the sensor reports it) and replace if low. 4. For wired sensors: verify the connection (Ethernet cable seated, USB cable connected, mounting secure). 5. For WiFi sensors: check signal strength at the device's location. 6. For BLE sensors: check distance to the BLE adapter or proxy; BLE range is limited and obstructions matter. 7. For Zigbee sensors: check whether the device is responsive to commands (for actuators) or has reported in a reasonable window (for pure sensors). Consider re-pairing if persistently silent. 8. Check the Home Assistant log for errors mentioning the specific device or sensor.

Common causes.

- Dead battery. The most common cause for battery-powered sensors. Typically silent failure — no explicit error, just no new readings. - Network issue. For WiFi devices, marginal signal or network problem. For BLE, range or interference. For Zigbee/Z-Wave, mesh issues or coordinator problems. - Device hardware failure. Less common but real. A sensor chip failure that leaves the device apparently online but not producing readings. - Integration-level issue. A specific integration-side problem affecting this device (rare; usually the whole integration suffers). - Firmware bug. After a firmware update, a specific device type may misbehave.

Resolution paths.

- Replace batteries. For battery-powered devices with low or unreported battery levels. - Improve signal. Move the device, add a repeater, or change to wired where the environment makes wireless unreliable. - Re-pair the device. For Zigbee/Z-Wave devices that have fallen off the mesh. - Replace the device. For hardware failure. - Check for device-specific fixes. Integration-specific or device-specific issues often have community-known workarounds.

Prevention. Monitor sensor freshness (dead-man switches, per [Monitoring Home Assistant Itself](/home-assistant/operations/monitoring)) so silent failures are noticed within hours, not days. Proactive battery replacement on a schedule.

See also. [ESPHome](/home-assistant/integrations/esphome), [Zigbee](/home-assistant/integrations/zigbee), [Monitoring Home Assistant Itself](/home-assistant/operations/monitoring).

Recipe: The automation that should have fired but did not.

Symptom. A condition occurred that should have triggered an automation; the automation did not run; the expected action did not happen.

First check. Open the automation's trace history (click the automation, then the "Traces" tab). Is there a recent trace showing a run? If yes, the automation ran but something else is wrong (trace will show what). If no, the trigger did not fire.

Diagnostic steps.

1. If no recent trace exists: verify the trigger logic. Open the automation editor; check that trigger entity IDs are correct (not referring to a renamed or removed entity); check trigger conditions match current reality. 2. Verify the trigger's source entity is actually reporting the values expected. Use Developer Tools → States to check. 3. If the trigger references a template, test the template in Developer Tools → Template to verify it produces the expected result. 4. Check whether the automation is enabled. Toggled off automations produce no traces. 5. Check the automation mode (single, restart, queued, parallel). An earlier run still executing may block the new trigger. 6. If a recent trace exists: examine which step failed or which condition blocked execution. 7. Check for recent changes to the automation, to the source entity, or to Home Assistant itself.

Common causes.

- The automation was disabled. Someone toggled it off and did not re-enable it. Checked easily. - Entity reference is wrong. An entity rename or integration change changed the ID the automation references. - Condition blocks execution. The trace shows a condition evaluated false. The question is whether the condition should have been true — sometimes the condition is written incorrectly, sometimes the current state really is outside the expected condition. - Mode-related suppression. A single-mode automation with a previous run still executing ignores new triggers. - Template bug. A template trigger or condition has an error that prevents correct evaluation. - Entity is unavailable. A referenced entity in "unavailable" state causes conditions and triggers to misbehave.

Resolution paths.

- Re-enable the automation. If it was accidentally disabled. - Correct entity references. Update the automation to use current entity IDs. - Fix condition logic. If the condition is wrong for the intended behavior. - Adjust mode. If mode-related suppression is blocking legitimate re-triggers. - Fix templates. Use Developer Tools → Template to debug.

Prevention. Test automations after creation with known trigger conditions. Automation trace review as part of monitoring (per [Monitoring Home Assistant Itself](/home-assistant/operations/monitoring)) catches issues before they matter.

See also. [Automation Fundamentals](/home-assistant/automations/fundamentals), [Template Sensors](/home-assistant/automations/templates), [Advanced Automation Patterns](/home-assistant/automations/advanced-patterns).

Recipe: The automation that fired when it should not have.

Symptom. An automation ran at a time or under conditions where it should not have. The grower received a notification at 3 AM for a condition that was not actually concerning, or an action was taken that was not appropriate.

First check. Open the automation's trace for the unexpected run. The trace shows the trigger that fired, the conditions evaluated, and the actions taken.

Diagnostic steps.

1. Identify which trigger fired. For automations with multiple triggers, the trace names the specific trigger. 2. Examine the state at the moment of triggering. The trace shows the relevant entity values. 3. If the trigger fired but conditions should have blocked — examine the conditions' evaluation. What were the values? Were they what you expected? 4. Consider whether the trigger threshold is too tight. A numeric state trigger with no hysteresis can fire on sensor noise at the threshold boundary. 5. For template triggers, verify the template's logic. A subtle bug can produce true at unexpected times. 6. For state triggers, check whether the transition is real or a restart/reload artifact. Some state triggers fire on restart because the state is re-established as a transition. 7. Check whether the expected blocking condition references current entity states or cached state — a condition that says "if X then" may evaluate X at the wrong time in complex automations.

Common causes.

- Missing hysteresis on numeric triggers. Sensor noise at the threshold produces repeated triggers. - Startup transition triggering. Home Assistant restart causes state transitions that a state trigger interprets as real changes. - Template trigger logic bug. Jinja2 template evaluates true when it should not. - Missing time condition. An automation that should only fire during the day does not have a time condition; it fires at night too. - Entity unavailability interpreted as state change. An entity going to "unavailable" and back triggers state transitions. - Automation logic rushed. The automation was written in a hurry; the logic was not carefully tested.

Resolution paths.

- Add hysteresis. Separate trigger threshold (e.g., >85°F for 2 minutes) from recovery threshold (e.g., <82°F for 2 minutes). - Add time conditions. Restrict to hours when the alert actually matters. - Fix template logic. Test against edge cases. - Filter out startup transitions. Use `from:` and `to:` together; add conditions that confirm the state is stable. - Use `for:` on triggers. Requires the triggering condition to persist for a duration before firing.

Prevention. Test automations against edge cases before deploying. Review automation runs periodically, especially for new automations. Start conservative (more restrictive conditions) and relax as the behavior is proven.

See also. [Automation Fundamentals](/home-assistant/automations/fundamentals), [Advanced Automation Patterns](/home-assistant/automations/advanced-patterns), [Agricultural Automation Cookbook](/home-assistant/automations/cookbook).

Recipe: The host that rebooted without being told to.

Symptom. Home Assistant's uptime shows a recent restart the grower did not initiate. Possibly the host has restarted repeatedly over a short period.

First check. Look at the Home Assistant log for the period just before the restart. The log often shows what happened — a kernel panic, an out-of-memory kill, a hardware watchdog trigger.

Diagnostic steps.

1. Determine whether this is a single unexpected restart or a pattern of restarts. Uptime history through the Uptime sensor or historical graphs shows the frequency. 2. Check system resources just before the restart. Memory exhaustion, disk exhaustion, and CPU-driven hangs are common causes. 3. For Home Assistant OS or Supervised: check Supervisor logs (Settings → System → Repairs, or Supervisor logs through the CLI). Supervisor may have restarted Home Assistant for its own reasons. 4. For Docker deployments: check Docker logs for the Home Assistant container. Check container resource limits and whether they were exceeded. 5. Check the host's system logs (dmesg on Linux, journal entries) for hardware events, thermal events, or OS-level problems. 6. Check for scheduled reboots from OS-level automation (unattended upgrades on Ubuntu sometimes reboot; check their configuration).

Common causes.

- Out of memory. The host or the Home Assistant process ran out of memory; OOM killer terminated processes; Home Assistant restarted. - Disk full. Disk fills; critical writes fail; Home Assistant or the host crashes. - Hardware issue. RAM going bad, disk failing, power supply flaky. Intermittent hardware issues cause unexplained restarts. - Overheating. Systems throttling or shutting down due to heat. Check [Choosing Your Hardware](/home-assistant/hardware/choosing) cooling considerations. - Scheduled restart by another tool. Unattended upgrades, cron jobs, or manual scripts. - Home Assistant bug. Rare; sometimes a specific feature triggers a crash.

Resolution paths.

- Address resource constraints. Add memory (physical or swap), clean disk space, reduce integrations or history if needed. - Replace failing hardware. Run memory tests, disk health checks (SMART data). Replace suspect components. - Improve cooling. Better ventilation, cleaner air intake, relocate the host if it is in a warm location. - Review OS-level automation. Adjust scheduled reboots to predictable times; disable surprises. - Report Home Assistant bugs. If the restart is clearly Home Assistant-caused and reproducible, file an issue.

Prevention. Host health monitoring (CPU, memory, disk, temperature). Hardware that suits the workload (graybox framing per [Choosing Your Hardware](/home-assistant/hardware/choosing)). Scheduled maintenance (RAM tests, disk checks) catches wear before it causes failures.

See also. [Monitoring Home Assistant Itself](/home-assistant/operations/monitoring), [Choosing Your Hardware](/home-assistant/hardware/choosing), [Backup and Recovery](/home-assistant/operations/backup).

Recipe: The Zigbee mesh that partially failed.

Symptom. Some Zigbee devices are unreachable; others work normally. The pattern does not obviously correlate to anything specific.

First check. Examine the mesh map if the Zigbee integration provides one (Zigbee2MQTT has an excellent map; ZHA has one too). Look for devices that are disconnected or that have poor link quality.

Diagnostic steps.

1. Identify the unreachable devices. Are they all the same type, the same manufacturer, in the same location? 2. Check link quality (LQI) values for the affected devices and for nearby devices. Low LQI indicates poor signal. 3. Check whether the unreachable devices are battery-powered (end devices) or mains-powered (routers). End devices drop off more easily than routers but also matter less to the mesh. 4. Verify the coordinator is healthy. A coordinator with issues affects the whole mesh. 5. Check for recent additions — devices added to the mesh can destabilize it briefly. 6. Check for interference. Zigbee operates in the 2.4GHz band; WiFi, Bluetooth, and some other devices can cause interference. Channel changes can help. 7. Consider mesh topology. A mesh that depends on a single weak link has a fragile path.

Common causes.

- Weak link quality due to range or obstruction. Zigbee has limited range; metal buildings or dense crops can attenuate signal. - Dead batteries on end devices. Common and silent; check battery levels where reported. - Coordinator issues. Failing coordinator affects everything. Coordinator location matters — it should be central, away from sources of interference. - Interference from other 2.4GHz devices. WiFi on the same channel, Bluetooth proximity, certain microwave equipment. - Router devices removed. A mesh that relied on specific router devices breaks if those devices are removed or unplugged. - Firmware issues. Specific device firmware can cause mesh issues.

Resolution paths.

- Improve signal. Move the coordinator or add Zigbee repeaters. Powered router devices (smart plugs, typically) extend mesh coverage. - Replace batteries. For end devices with low batteries. - Change Zigbee channel. If WiFi or other 2.4GHz interference is identified. - Re-pair devices. Devices that have lost mesh position sometimes recover with re-pairing. - Replace the coordinator. If it appears to be the cause.

Prevention. Mesh monitoring. Regular review of the mesh map. Purposeful placement of router devices for coverage. Proactive battery replacement. Channel selection aware of WiFi usage.

See also. [Zigbee](/home-assistant/integrations/zigbee), [Monitoring Home Assistant Itself](/home-assistant/operations/monitoring).

Recipe: The integration with slow or failing service calls.

Symptom. Calling a service (turning on a switch, sending a notification, running a script) takes a long time or fails. The Home Assistant UI appears sluggish when interacting with the affected integration.

First check. Developer Tools → Services: manually call the service that is slow. Watch how long it takes and whether it produces any error.

Diagnostic steps.

1. Determine whether the slowness affects all services or a specific category (cloud services, specific integrations). 2. If cloud service: check the provider's status page for known outages. 3. If local integration: check the device's network state. Pings from the Home Assistant host to the device can reveal network issues. 4. Check Home Assistant's CPU and memory. A resource-starved host is slow on everything. 5. Check for blocking operations in Home Assistant's log. Warnings about slow service calls or event loop blocks appear there. 6. Check database performance if the slow service writes to the recorder. An oversized or corrupted database can slow Home Assistant significantly.

Common causes.

- Cloud service outage or degradation. External services have outages that affect the integration's performance. - Local network issues. Packet loss, high latency, or DNS issues between Home Assistant and the target device. - Database performance. A bloated recorder database affects every state change. - Integration bugs. Specific integrations sometimes have performance issues that surface under load. - Host resource exhaustion. CPU or memory pressure affects everything.

Resolution paths.

- Wait it out if cloud-caused. Temporary cloud outages typically resolve; local redundancy protects against extended outages. - Investigate the local network. Use ping, traceroute, and similar tools to identify the network problem. - Tune the recorder. Purge old data, exclude noisy entities from recording, consider MariaDB if SQLite is the bottleneck. - Report integration bugs. With specific details and logs, integration authors can address performance issues. - Upgrade hardware. If the host is persistently resource-constrained, the solution may be better hardware (per [Choosing Your Hardware](/home-assistant/hardware/choosing)).

Prevention. Host capacity planning. Database maintenance. Monitoring catches resource issues before they affect service calls.

See also. [Monitoring Home Assistant Itself](/home-assistant/operations/monitoring), [Choosing Your Hardware](/home-assistant/hardware/choosing), [Backup and Recovery](/home-assistant/operations/backup) for database backup considerations.

Recipe: The update that broke things.

Symptom. Home Assistant was updated; something stopped working. The specific breakage varies — integrations failing to load, automations erroring, UI behaving differently.

First check. Read the release notes for the installed version. Breaking changes are documented; often the broken thing is mentioned with guidance.

Diagnostic steps.

1. Identify what specifically is broken. Which integration, which automation, which UI element? 2. Check the release notes for mentions of the broken component. 3. Check the Home Assistant log for errors that appeared after the update. 4. For custom integrations (HACS): check whether the custom integration has an update compatible with the new Home Assistant. 5. Consider rolling back to the previous version if a clean fix is not available.

Common causes.

- Breaking changes in Home Assistant core. Announced in release notes; configuration or automation changes are typically required. - Custom integration incompatibility. Community integrations update on their own schedules. - Configuration format changes. YAML syntax updates that the older syntax no longer passes. - Removed features. Features that were deprecated for several releases are eventually removed. - Integration-side changes driven by the update. Home Assistant changes sometimes cascade to integration behavior even without explicit breaking changes.

Resolution paths.

- Follow release notes. Breaking changes usually include migration instructions. - Update custom integrations. HACS or direct update for components that need to catch up. - Adjust configuration. Update YAML to the current syntax. - Rollback. For operations that cannot wait for a fix, rolling back to the previous version restores operation. The [Updates and Version Management](/home-assistant/operations/updates) page covers rollback specifics.

Prevention. Read release notes before updating. Back up before updating. Test on a staging system when possible. Update at a time when operational impact is manageable (not during critical growing phases).

See also. [Updates and Version Management](/home-assistant/operations/updates), [Backup and Recovery](/home-assistant/operations/backup).

Recipe: The database that is causing performance issues.

Symptom. Home Assistant is slow. Restart takes minutes. Dashboards load slowly. History graphs take a long time to render. The Home Assistant log may show warnings about database operations.

First check. Check the size of the recorder database. For SQLite, look at `/config/home-assistant_v2.db`. A database over a few gigabytes is probably affecting performance.

Diagnostic steps.

1. Identify the database size. 2. Check the recorder configuration. What is being recorded? A default recorder records every entity's state changes; with hundreds of entities, this grows fast. 3. Check purge settings. The recorder can be configured to purge data older than a specified period. 4. Identify noisy entities — entities that change state very frequently. Signal strength sensors, statistic sensors, and some template sensors can generate many state changes per minute. 5. Consider MariaDB. SQLite performance degrades at larger sizes; MariaDB (or PostgreSQL) handles large databases better.

Common causes.

- Default recorder configuration on an installation with many entities. Grows unbounded. - Short purge retention but very high event volume. Recent data is fine, but the high ingest rate creates I/O pressure. - Noisy entities bloating the database. A few entities generating thousands of events per day dominate. - SQLite hitting its comfortable size limit. Multi-gigabyte SQLite databases struggle.

Resolution paths.

- Configure purge retention. Set `purgekeepdays` in the recorder configuration. A week to a month is common for most installations; longer if that history matters. - Exclude noisy entities from recording. Use `recorder:` configuration's `include`/`exclude` sections to specify what gets recorded. - Migrate to MariaDB. For installations where SQLite has become a bottleneck. - Manual database cleanup. In extreme cases, manual purging or even starting fresh (after backing up) may be warranted.

Prevention. Thoughtful recorder configuration from the start. Periodic review of database size. Monitoring that alerts on database size growing beyond expected bounds.

See also. [Backup and Recovery](/home-assistant/operations/backup), [Monitoring Home Assistant Itself](/home-assistant/operations/monitoring), [Grafana Integration](/home-assistant/dashboards/grafana) for long-term data storage that complements the recorder.

Recipe: The ESPHome device that will not flash.

Symptom. An ESPHome device — an ESP32 or ESP8266 running custom firmware — will not accept a new firmware image. OTA updates fail; initial USB flashing fails.

First check. Determine whether this is an OTA failure (device is running, reachable over WiFi, but the update does not complete) or a USB flash failure (device is not on WiFi, physical connection).

Diagnostic steps.

1. For OTA failures: verify the device is reachable on the network (ping, ESPHome dashboard status). Check whether the device is running its previous firmware correctly. 2. Check the ESPHome add-on or standalone ESPHome logs for the specific error during the flash attempt. 3. For USB flash failures: verify the USB cable is a data cable, not a charge-only cable. Try a different cable. Try a different USB port. 4. Check that the correct ESP board type and serial port are selected in the ESPHome configuration. 5. Some ESP boards require holding a boot button during flash. Consult the specific board's documentation. 6. Check for conflicting processes — another program may be holding the serial port.

Common causes.

- Charge-only USB cable. Very common; a cable that charges the device but does not carry data cannot flash it. - OTA auth key mismatch. ESPHome uses an OTA password or encryption key; if it does not match, the upload fails. - WiFi instability during OTA. Flash fails partway; device reboots into previous firmware (the OTA safety fallback). - Boot mode required. Some boards need manual intervention to enter flash mode. - Conflicting serial port usage. Another program has the port open. - Device has run out of flash space. Very large custom firmware can exceed the device's flash capacity.

Resolution paths.

- Use a known-good USB data cable. Replacement cables are cheap; eliminating the cable as a variable is the first step. - Check WiFi signal at the device location. Move the device or add a WiFi repeater if signal is marginal. - Re-verify OTA key. The key is in the device's current configuration; it must match on both sides. - Follow board-specific flash instructions. Some boards need boot-mode intervention; the documentation tells which. - Reduce firmware size. Remove features, use smaller libraries, disable debug options.

Prevention. Keep the ESPHome device's physical access available for recovery. Test OTA updates on non-production devices first. Document which cables work for flashing different devices.

See also. [ESPHome](/home-assistant/integrations/esphome).

Recipe: The restart that turned into a boot loop.

Symptom. Home Assistant attempts to start but fails repeatedly. The system appears to be stuck restarting over and over. No stable state; nothing works.

First check. Access the Home Assistant logs through the host's console or SSH (not through the Home Assistant UI, which is not running). The logs show why each restart attempt is failing.

Diagnostic steps.

1. Access the host directly — through the console, through SSH, or by connecting a monitor and keyboard. 2. Find the Home Assistant startup log. Location varies by installation type; typically in the configuration directory or accessible through Supervisor / Docker commands. 3. Identify the error that prevents successful startup. Common patterns include: - A custom integration error that crashes the startup. - A YAML configuration error that prevents parsing. - A database corruption issue. - A missing file or permission issue. 4. If a specific custom component is the cause, temporarily remove its configuration (or the component itself from `custom_components/`) and try again. 5. If a YAML configuration error: use the config check command to validate the configuration before starting. 6. If database corruption: restore the database from backup (or start with a fresh database as a temporary measure; data is lost but operation resumes).

Common causes.

- Custom integration that breaks on startup. A recent update or configuration change to a custom component crashes Home Assistant during startup. - YAML syntax error. A typo or misplaced configuration in an automation or other file. - Database corruption. The recorder database is corrupt; Home Assistant cannot open it. - Missing or moved file. A file referenced by the configuration no longer exists. - Resource constraints. The host does not have enough memory or disk to start Home Assistant.

Resolution paths.

- Remove or disable the problematic custom component. Move it out of `custom_components/` temporarily; restart. - Fix the YAML error. The startup log usually names the file and line. - Restore from backup. If the root cause is unclear or affects multiple things, restoring from a known-good backup is the fastest path. - Fresh database start. Move the corrupted database aside; Home Assistant creates a new one on startup. Recent state history is lost but operation resumes. - Address resource issues. Free up disk space, add memory, as appropriate.

Prevention. Backup before changes. Test custom integrations on a separate system before production use. Validate YAML before deploying changes.

See also. [Backup and Recovery](/home-assistant/operations/backup), [Updates and Version Management](/home-assistant/operations/updates).

Recipe: The dashboard that is not loading.

Symptom. The Home Assistant dashboard is blank, shows errors, or takes an unusually long time to load. Specific cards may show "Error" or "Unavailable." The UI overall may be sluggish.

First check. Browser cache and cookies. A corrupted cache can cause dashboard issues; a hard refresh (Ctrl+Shift+R on most browsers) or clearing the browser cache sometimes resolves it immediately.

Diagnostic steps.

1. Hard refresh the page to rule out cached issues. 2. Try the dashboard from a different device (phone vs. laptop) to isolate browser-side vs. server-side. 3. Open the browser's developer console (F12) and look for JavaScript errors or failed network requests. 4. Check whether a specific card is the problem. Sometimes one broken card affects the whole dashboard; identifying which one narrows the issue. 5. For custom cards (HACS): verify the card is still installed and compatible with the current Home Assistant. 6. Check whether the problem is dashboard-specific (one particular dashboard fails) or installation-wide (all dashboards affected).

Common causes.

- Browser cache issues. A stale cache after a Home Assistant update. - Broken custom card. A HACS card that is not compatible with the current Home Assistant version. - Template errors in markdown or other cards. A template referencing an entity that no longer exists. - Resource exhaustion. Home Assistant is overloaded and cannot serve the dashboard quickly. - Network issues. Between the browser and Home Assistant.

Resolution paths.

- Clear browser cache or hard refresh. First try; fixes a surprising percentage of dashboard issues. - Disable problematic custom cards. Identify through process of elimination; update or replace. - Fix template errors. Use Developer Tools → Template to verify templates. - Check Home Assistant resources. If the installation is overloaded, the UI is a symptom, not the cause.

Prevention. Minimize custom card usage for critical dashboards. Test after Home Assistant updates. Keep dashboards focused (per [Dashboard Design for Growers](/home-assistant/dashboards/design)); excessive card count contributes to slow loading.

See also. [Dashboard Design for Growers](/home-assistant/dashboards/design), [Lovelace Fundamentals](/home-assistant/dashboards/lovelace), [Cards That Matter for Agriculture](/home-assistant/dashboards/agricultural-cards).

Recipe: The notification that never arrived.

Symptom. An automation should have sent a notification; it did not. The grower did not receive the alert; the phone did not ring; the SMS did not come through.

First check. Verify that the automation actually ran. Open its trace history; if the automation did not run, the notification failure is really an automation failure (see the "automation did not fire" recipe). If the automation did run, investigate the notification side.

Diagnostic steps.

1. In the automation trace, verify the notification action ran. Did the service call execute? Did it produce an error? 2. Test the notification service manually. Developer Tools → Services → pick the notification service → Send Test. Does the notification arrive? 3. For mobile app notifications: check app permissions (notifications enabled on the phone, Home Assistant app allowed to send notifications). 4. For SMS via a cloud service (Twilio, etc.): check the service's logs for whether the message was accepted or failed. 5. For email: check spam folder; check that the sender is not blocked. 6. Check Home Assistant's log for errors related to the notification service.

Common causes.

- Mobile app notifications disabled. Phone-level or app-level notification permissions changed. - Service credential expiration. Cloud notification services (Twilio, Telegram bots, etc.) can have credential issues. - Rate limiting. Some notification services rate-limit aggressive senders; too many notifications in a short window can result in some being dropped. - Targeting error. The notification service targets a specific device or user; the target may be wrong or no longer exist. - Platform-side issues. Apple and Google's push infrastructure occasionally has delays or issues.

Resolution paths.

- Re-enable notifications on the phone. Check the Home Assistant app's notification settings and the phone's overall notification settings for the app. - Update credentials. For cloud services, rotate keys or re-authenticate as needed. - Reduce notification volume. Deduplicate alerts; rate-limit automation triggers; aggregate related notifications. - Correct targeting. Verify the device or user ID is correct. - Retry after platform issues. Brief platform outages usually resolve quickly.

Prevention. Periodic notification tests (per the monitoring discipline). Rate-limiting automations that could flood notifications. Maintaining credentials (rotation, monitoring for expiration).

See also. [Notification Services](/home-assistant/integrations/notifications), [Monitoring Home Assistant Itself](/home-assistant/operations/monitoring).

Recipe: The remote access that is not working.

Symptom. The grower cannot reach Home Assistant from outside the local network. Local access still works. The mobile app shows "not connected" when away from home; the browser cannot load the external URL.

First check. What remote access method is configured? Nabu Casa, VPN, reverse proxy? The diagnosis differs by method.

Diagnostic steps.

1. For Nabu Casa: check Nabu Casa status (status.nabucasa.com or similar). Log into the account to verify the subscription is active and the connection is healthy. 2. For VPN: verify the VPN client on the remote device is connected. Check the VPN server's status. 3. For reverse proxy: verify the proxy is running. Check certificate validity. Check that the proxy's public IP (or domain) still points to the right place. 4. For all methods: verify the Home Assistant host is reachable from the local network. If local access is broken too, the problem is with Home Assistant, not remote access. 5. Check the Home Assistant log for errors related to the remote access integration. 6. Check the router for recent changes — firmware updates sometimes reset port forwards or affect VPN configurations.

Common causes.

- Nabu Casa outage or subscription lapse. - VPN server down or unreachable. - Reverse proxy certificate expired. - Public IP change. The operation's public IP changed and DNS has not updated. - Router configuration lost. Port forwards or VPN rules lost after a firmware update. - ISP-side changes. CGNAT (carrier-grade NAT) changes that affect direct inbound connectivity.

Resolution paths.

- Verify Nabu Casa. Sign in, check status, contact support if needed. - Restart VPN server or client. Brief restart often resolves temporary issues. - Renew certificate. Automated renewal should handle this; manual renewal if it did not. - Update DNS. Dynamic DNS catches IP changes automatically; if it was not configured, public IP changes break access. - Reconfigure router. After firmware updates, verify the configuration is intact.

Prevention. Monitoring (certificate expiration, connection tests from outside). Dynamic DNS for operations with non-static public IPs. Regular verification that remote access works — do not wait until you need it.

See also. [Remote Access](/home-assistant/operations/remote-access), [User Management and Security](/home-assistant/operations/security), [Monitoring Home Assistant Itself](/home-assistant/operations/monitoring).

Common themes across recipes.

Patterns that recur throughout Troubleshooting.

Read the log first. Most problems announce themselves in the Home Assistant log. Starting there saves time versus guessing.

Check what changed recently. A problem that appeared today correlates with something that changed recently. The change log is often the fastest path to the cause.

Reproduce deliberately. Understanding requires reproduction. A problem that cannot be reproduced is hard to fix with confidence; a problem that can be reproduced narrows to its cause quickly.

Change one thing at a time. Multiple simultaneous changes obscure which change mattered. Single-change discipline makes diagnosis efficient.

Backup before invasive changes. Troubleshooting sometimes goes wrong. A backup gives a return path.

Document what you find. Future troubleshooting benefits from past troubleshooting. Short notes (what the symptom was, what the cause turned out to be, what the fix was) compound into real value.

Use the community. The Home Assistant community forum and GitHub issues often have specific problems already answered. A focused search with the specific error message is often faster than diagnosis from scratch.