Onboarding creates awareness for unsupported installation methods

[frenck]

Problem statement

Users who install Home Assistant through unsupported or non-official installation methods (e.g., third-party NAS app stores, community Docker guides with non-standard configurations, unofficial packages) often end up with an experience where certain features do not work as intended. Apps may be missing, onboarding may behave unexpectedly, or updates may fail. Because these users are unaware that their installation method is the root cause, they attribute the problems to Home Assistant itself. This leads to frustration, negative first impressions, and in some cases, users abandoning the platform entirely.

Today, Home Assistant has no mechanism during onboarding to inform a user that they are running on an unsupported installation method, what that means for their experience, and what the officially supported alternatives are. The "unsupported installation" messaging that exists is buried deep in the UI and only relevant for Supervisor-based installs. For users on third-party containers or other non-official setups, there is no proactive communication at all during their critical first interaction with the product.

This directly undermines OHF's goal to make Home Assistant more approachable. A user's very first experience should set clear expectations. If we cannot guarantee a smooth experience on their current setup, we owe it to them to say so upfront, before frustration sets in, not after.

Scope & Boundaries

In scope

• Detect during onboarding whether the current installation uses an unsupported or non-official method
• Display a clear, non-blocking acknowledgment screen during the onboarding flow explaining that the user is running an unsupported installation
• Explain in user-friendly language what "unsupported" means in practice (e.g., certain features may not be available, the project cannot guarantee a smooth experience, community support may be limited)
• Recommend the officially supported installation methods (Home Assistant OS, Home Assistant Container via the official image)
• Link to the official installation documentation for migration guidance
• Allow the user to acknowledge and continue with their current setup (non-blocking)

Not in scope

• Blocking users from using unsupported installation methods
• Changing how installation methods are detected at the system level (we rely on existing detection)
• Addressing the root causes of why features break on unsupported installations
• Deprecation or removal of any installation method
• Ongoing persistent warnings after onboarding (this is about the first-run experience only)

Foreseen solution

During the onboarding flow, after the initial system setup but before the user begins configuring their home, Home Assistant checks the detected installation method. If the installation is identified as unsupported or non-official, an additional onboarding step is presented.

This step should:

1. Clearly communicate that the detected installation method is not officially supported by the Home Assistant project
2. Explain, in plain language, the practical implications: some features may be unavailable, certain behaviors may differ from what documentation describes, and the project may not be able to help troubleshoot issues caused by the installation method
3. Recommend the user consider migrating to an officially supported installation method, with a direct link to the installation documentation
4. Provide an explicit acknowledgment action (e.g., "I understand, continue anyway") so the user can proceed without being blocked

The tone should be helpful and informative, not punitive. The goal is awareness, not gatekeeping.

Community signals

The community forums and issue trackers show a long and consistent pattern of users running into problems caused by unsupported installation methods, often without realizing the installation itself is the cause:

• Numerous forum posts from users on Synology, QNAP, and Unraid NAS devices who install Home Assistant via Docker but then cannot find Apps, the Supervisor, or other expected features (example, example, example, example)
• Multiple threads from users confused about what "unsupported installation" means and how to resolve it (example, example, example)
• Users running non-root containers or modified Docker setups being flagged as "Unsupported Third Party Container" without understanding why (example)
• Onboarding failures specifically tied to non-standard Docker or NAS-based installations (example, example, example)
• Users who don't even know what installation type they are running (example)
• The recent deprecation of Core and Supervised installation methods (2025.12) has narrowed the officially supported methods to Home Assistant OS and Container, making this awareness gap even more relevant going forward

Risks & open questions

• Detection reliability: How reliably can we detect unsupported installation methods during onboarding? We should rely on existing installation type detection rather than building new detection mechanisms. If detection is unreliable for certain edge cases, we should err on the side of not showing the warning.
• Tone and framing: The messaging needs to inform without alienating. Users on unsupported installs are often technically capable and have made a deliberate choice. The screen should respect that while still being clear about the implications.
• Maintenance: As the landscape of installation methods evolves, the detection and messaging need to stay current. This should be straightforward if we rely on the existing installation type detection infrastructure.
• Third-party container detection: Can we reliably distinguish between the official Home Assistant container image and third-party or modified container images?

Appetite

Small, roughly 1 cycle of focused work, primarily in core and frontend.

Execution issues

To be populated once a bet is approved.

Decision log

Date	Decision	Outcome
2026-03-11	Created opportunity for betting table consideration	Addressing a long-standing source of user frustration tied to the approachability goal