Home Assistant says “Unsupported system”: diagnose Supervisor warnings safely

Direct answer: An “Unsupported system” warning is not one single fault. It is Supervisor reporting that a specific host requirement—such as the operating system, OS-Agent, AppArmor, D-Bus, NetworkManager, systemd-resolved, CGroup v2, or the Home Assistant OS version—does not meet its supported baseline. Open Settings → System → Repairs, identify the exact unsupported check, and fix that check rather than suppressing the warning.

This guide applies to Home Assistant OS and supervised installations that expose Supervisor and the Repairs dashboard. It does not apply to Home Assistant Container or Core installations, which do not use Supervisor’s supported-host evaluation in the same way.

Symptoms and affected scope

A Repairs notification says the installation or system is unsupported.
Supervisor stops offering some updates or repeatedly logs an unsupported condition.
The warning appeared after a host OS change, a kernel change, installing extra host software, or restoring an older image.
The system still appears to work, which makes it tempting to ignore the warning.

These symptoms can look similar even though their causes sit in different layers. The safest approach is to preserve the current working state, identify the first failing layer, and change one variable at a time. This prevents a recoverable Home Assistant unsupported system problem from turning into lost pairings, lost entities, or an inaccessible installation.

Ranked likely causes

1. Home Assistant OS is more than four major releases behind.
2. A supervised installation is running on an unsupported operating system or an altered host.
3. OS-Agent is missing, stopped, outdated, or unreachable.
4. AppArmor, D-Bus, NetworkManager, systemd-resolved, or CGroup v2 is absent or misconfigured.
5. Unsupported extra software or conflicting containers are installed on the supervised host.

Before changing anything

Make a current backup, record versions and installation type, capture the exact first error, and remove secrets from any notes. Do not delete integrations, reset devices, erase databases, or reflash firmware as an opening move. If equipment is hot, swollen, wet, arcing, smoking, or connected to mains wiring that must be opened, stop and use qualified help.

Least-destructive diagnostic order

1. Create a current full backup and download a copy away from the Home Assistant host. Confirm that the backup appears in the backup list and retain the encryption emergency kit if encryption is enabled. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
2. Open Settings → System → Repairs and expand the unsupported item. Record the exact check name and the suggested more-info link. Do not treat the umbrella phrase “unsupported system” as the diagnosis. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
3. Check Settings → System → Updates. If Home Assistant OS is old, update one offered OS release at a time and allow the host to finish rebooting. Do not remove power during an operating-system update. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
4. For an OS-Agent warning, confirm the service exists and is running using the official OS-Agent instructions for the supervised host. Home Assistant OS already includes OS-Agent; an OS installation showing this warning should normally be rebooted and updated before deeper host changes. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
5. For an AppArmor warning, verify the kernel boot parameters and AppArmor service rather than disabling the check. AppArmor is part of the supported security boundary. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
6. For D-Bus, NetworkManager, systemd-resolved, or CGroup warnings, compare the host with the official supported supervised-installation requirements. Correct the named service only; do not replace several networking components at once. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
7. If the warning names unsupported software, inventory containers and packages added outside Home Assistant. Stop only the conflicting component after documenting its configuration. Avoid deleting volumes or configuration while diagnosing. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
8. If the operating system itself is unsupported, plan a backup-and-restore migration to Home Assistant OS or another officially supported installation type. A clean migration is safer than forcing Supervisor to accept an incompatible host. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.

Choose the correct branch

Home Assistant OS: prioritize OS updates, a controlled reboot, storage health, and official recovery procedures.
Supervised: verify the exact supported Debian release and every required host service before changing Supervisor.
Container or Core: the message likely comes from a different component or an old supervised configuration; confirm the actual installation type before following supervised-host commands.

How to interpret the results

If the evidence points to Home Assistant OS is more than four major releases behind. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

If the evidence points to a supervised installation is running on an unsupported operating system or an altered host. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

If the evidence points to oS-Agent is missing, stopped, outdated, or unreachable. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

If the evidence points to appArmor, D-Bus, NetworkManager, systemd-resolved, or CGroup v2 is absent or misconfigured. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

If the evidence points to unsupported extra software or conflicting containers are installed on the supervised host. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

Verified repair and final checks

Return to Repairs after the repair and select recheck when offered. Confirm that the exact unsupported condition disappears, Supervisor can refresh update information, backups remain visible, add-ons start, and the host survives one controlled reboot. A working dashboard alone is not proof that the host is supported.

A repair is not verified merely because an error banner disappears. Confirm the underlying connection or service, observe fresh state data, and test after a controlled restart where appropriate. Keep the previous configuration until the new state has remained stable.

Rollback and recovery

If a service change breaks networking, use local console access and reverse only the last documented change. If migration fails, reinstall the prior supported image and restore the downloaded backup. Never test recovery by deleting the only working installation.

Write down each change before making it. Reversibility matters: a documented URL, service setting, serial path, integration state, or firmware version is much easier to restore than a configuration changed in several places at once.

Prevention

Keep Home Assistant OS and Supervisor current, avoid placing unrelated workloads on a supervised host, document host-level modifications, retain off-device backups, and review Repairs after every host or kernel update.

Review this setup after platform, firmware, router, certificate, or host changes. Backups should exist off the device and should be periodically checked for visibility and required encryption material.

Privacy and safety

Never publish access tokens, API keys, encryption keys, Wi-Fi credentials, public IP addresses, precise locations, camera URLs, door-lock states, alarm details, or complete unsanitized diagnostics. Do not weaken TLS, firewall rules, authentication, or network isolation simply to make an error disappear.

Testing disclosure

This guide is based on the current official documentation and linked upstream reports. Troubliq did not physically test every device, adapter, network, phone, host, or installation variant described. Device-specific behavior can differ; preserve backups and follow the manufacturer’s safety instructions.

Sources

Last reviewed: September 24, 2026.

Next: use the Home Assistant Error Decoder to match the exact message, or return to the current Home Assistant problems hub.

Detailed diagnostic reference

Read the exact Repairs identifier

Supervisor groups several host checks under an unsupported-system banner. Preserve the identifier shown in Repairs and the linked more-info page. An operating-system check, OS-Agent check, AppArmor check, D-Bus check, NetworkManager check, systemd-resolved check, and CGroup check require different remedies; treating them as one warning causes unnecessary host changes.

Separate unsupported from unhealthy

Unsupported describes a configuration outside the maintained baseline. Unhealthy can block Supervisor operations because a required service or condition is currently failing. Record both states independently. Clearing an unsupported notice does not prove the host is healthy, and a healthy-looking dashboard does not prove the installation is supported.

Check update visibility

An outdated Home Assistant OS can stop Supervisor from refreshing component update information. Compare the installed OS release with the releases offered in Settings. If updates are absent while the OS is far behind, use the official OS recovery path rather than installing random packages on the host.

Plan a supervised-host migration

Before migrating, inventory add-ons, storage mounts, USB devices, static addresses, certificates, and external databases. Download a full backup and its emergency kit. Install the supported target, restore the backup, then verify each hardware path and network dependency before decommissioning the old host.

Document host services

For supervised installations, record the status of OS-Agent, AppArmor, D-Bus, NetworkManager, systemd-resolved, Docker, and CGroup v2. Change only the service named by the repair. A broad package upgrade or networking replacement can create a second failure while hiding the first.

Avoid suppressing the symptom

Ignoring or hiding a Repairs notification does not restore support. Do not patch Supervisor files, disable evaluation code, or spoof the operating-system identity. Those changes make future updates less predictable and remove useful evidence from support requests.

Verify storage before upgrades

Low free space, filesystem errors, and failing media can make an ordinary update look like a Supervisor compatibility problem. Check storage health and available space before a major OS update. Keep the backup off the same storage device.

Prepare local recovery access

Host-level networking repairs can remove remote access. Confirm local console access, the device location, and a rollback path before changing NetworkManager, DNS, or firewall configuration. For remote installations, schedule an onsite fallback rather than gambling on an untested network restart.

Escalation package

A useful support package includes installation type, Core/Supervisor/OS versions, the exact Repairs identifier, relevant sanitized Supervisor lines, recent host changes, and the result of the official recheck. Exclude tokens, public addresses, serial numbers when unnecessary, and complete backups.

Completion criteria

The repair is complete only when the named Repairs item clears, Supervisor refreshes update data, add-ons and backups remain available, networking survives a controlled reboot, and no replacement unhealthy condition appears. Record the final versions and change that resolved it.

When the warning returns after a reboot

If the same repair returns after every restart, look for a persistent host configuration rather than repeatedly selecting recheck. Confirm that required services are enabled at boot, the correct kernel parameters remain active, the supported operating-system release is actually running, and no startup automation recreates a conflicting container or network configuration. Compare the first Supervisor evaluation after boot with the later state. A condition that appears only during startup may indicate service ordering; a condition that remains indicates the requirement is still unmet. Record boot logs before restarting again, because later logs may omit the first failure.