Skip to content

Fix "Invalid handler specified" error on initial config flow setup#7

Draft
Copilot wants to merge 3 commits intomainfrom
copilot/fix-initial-setup-error
Draft

Fix "Invalid handler specified" error on initial config flow setup#7
Copilot wants to merge 3 commits intomainfrom
copilot/fix-initial-setup-error

Conversation

Copy link
Contributor

Copilot AI commented Mar 17, 2026

When loading the integration, HA's Python 3.14 environment raises cannot import name 'wrap' from 'aiofiles.base' because the installed version of aiofiles no longer exposes wrap from aiofiles.base. This ImportError occurs while loading __init__.py (which runs before config_flow.py can be registered), so HA cannot find the config flow handler and returns "Invalid handler specified".

Changes

  • __init__.py: Replace aiofiles.ospath.exists with os.path.exists for key file validation.

  • coordinator.py: Remove aiofiles imports and replace async file operations with hass.async_add_executor_job(Path(...).exists) and hass.async_add_executor_job(Path(...).read_text) — the HA-recommended pattern for executor-based file I/O.

  • manifest.json / requirements.txt: Remove the aiofiles==25.1.0 requirement entirely, eliminating the version conflict with HA's bundled aiofiles.

Original prompt

This section details on the original issue you should resolve

<issue_title>Error at initial setup</issue_title>
<issue_description>Fout
Config-flow kon niet geladen worden: {"message":"Invalid handler specified"}
</issue_description>

<agent_instructions>Any idea why this might happen?</agent_instructions>

Comments on the Issue (you are @copilot in this section)


💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

Move ConfigFlowResult import under TYPE_CHECKING to prevent
ImportError on HA versions < 2024.4.0. Add minimum homeassistant
version to manifest.json.

Co-authored-by: gensyn <36128035+gensyn@users.noreply.github.com>
Copilot AI changed the title [WIP] Fix error at initial setup Fix "Invalid handler specified" error on initial config flow setup Mar 17, 2026
Copilot AI requested a review from gensyn March 17, 2026 15:31
@gensyn
Copy link
Owner

gensyn commented Mar 17, 2026

@copilot Revert those changes, they don't work. Then have another look at the issue, there is new information.

The actual error was 'cannot import name wrap from aiofiles.base'
because the aiofiles version in HA's Python 3.14 environment does not
expose wrap from aiofiles.base. This causes an ImportError when loading
__init__.py, preventing the config flow handler from being found.

Remove aiofiles entirely and replace with:
- os.path.exists() in __init__.py for key file validation
- hass.async_add_executor_job(Path.exists/read_text) in coordinator.py

Also reverts the incorrect ConfigFlowResult TYPE_CHECKING fix.

Updates tests to patch os.path.exists and pathlib.Path.exists instead
of the removed ssh_command.exists / ssh_command.coordinator.exists.

Co-authored-by: gensyn <36128035+gensyn@users.noreply.github.com>
Copy link
Contributor Author

Copilot AI commented Mar 17, 2026

@copilot Revert those changes, they don't work. Then have another look at the issue, there is new information.

Reverted the previous incorrect fix. The real error (from the HA logs) was cannot import name 'wrap' from 'aiofiles.base' — the aiofiles version in HA 2026.3.2's Python 3.14 environment doesn't expose wrap from aiofiles.base, causing an ImportError when loading __init__.py, which in turn prevents the config flow handler from being found.

Fixed in cc4a319 by removing the aiofiles dependency entirely:

  • __init__.py: aiofiles.ospath.existsos.path.exists
  • coordinator.py: aiofiles.open + aiofiles.ospath.existshass.async_add_executor_job(Path.exists/read_text)
  • Removed aiofiles==25.1.0 from manifest.json and requirements.txt

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Error at initial setup

2 participants