Report a missing docker executable clearly and add error codes to config flow errors

README.md

@@ -158,7 +158,7 @@ When **Check for updates** is enabled for a container entry, SSH Docker also cre
 
 Navigate to **Settings → Updates** in Home Assistant. Containers with a pending image update are listed there. Click the container's update card and then **Install** to trigger a container recreation using the `docker_create` executable on the remote host — exactly the same operation as clicking **⬆ Update** in the sidebar panel.
 
-> **Requires** the `docker_create` executable to be present on the remote host. See [Custom Executables](#%EF%B8%8F-custom-executables) for details.
+> **Requires** the `docker_create` executable to be present on the remote host. See [Custom Executables](#-custom-executables) for details.
 
 While the installation is running the entity reports `in_progress: true` and the update card shows a progress indicator. Once completed the sensor is refreshed automatically to reflect the new container state.
 
@@ -385,6 +385,24 @@ Community contributions for additional languages are welcome!
 
 ---
 
+## ❗ Error Codes
+
+Errors shown while adding or reconfiguring a container are prefixed with a code.
+
+| Code | Meaning                                                                                                                                       | What to do                                                                                                                                                                                        |
+|------|-----------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| E001 | Neither password nor key file was provided.                                                                                                   | Provide one of them.                                                                                                                                                                              |
+| E002 | Cannot connect to the remote host.                                                                                                            | Check host, port and network.                                                                                                                                                                     |
+| E003 | The docker command exited with an error. This also happens if the executable was not found when the command is prefixed (e.g. `sudo docker`). | Check the docker command, that the executable exists on the host (use its absolute path, e.g. `sudo /usr/bin/docker`), and that the user may run it (e.g. `sudo` or docker group).                |
+| E004 | The host key could not be verified.                                                                                                           | Check the known hosts file or disable the known hosts check.                                                                                                                                      |
+| E005 | SSH login failed.                                                                                                                             | Check username and password/key file.                                                                                                                                                             |
+| E006 | Host is not reachable.                                                                                                                        | Check the host address and network.                                                                                                                                                               |
+| E007 | The connection timed out.                                                                                                                     | Check that the host is online and the port is correct.                                                                                                                                            |
+| E008 | The container name was not found on the host.                                                                                                 | Check the name with `docker ps -a` on the host.                                                                                                                                                   |
+| E009 | The docker executable was not found (exit status 127).                                                                                        | Non-interactive SSH sessions may not have `docker` on the `PATH` (common on QNAP/Synology NAS). Enter the absolute path as Docker Command (e.g. `/usr/bin/docker`) or symlink it into `/usr/bin`. |
+| E010 | The known hosts file was not found (SSH check enabled).                                                                                       | Provide the path to an existing known hosts file, create the default `~/.ssh/known_hosts` of the user running Home Assistant, or disable *Check Known Hosts*.                                     |
+| E011 | The known hosts file was provided but 'Check Known Hosts' is disabled.                                                                        | Either enable 'Check Known Hosts' or remove the known hosts file path.                                                                                                                            |
+
 ## ⚠️ Known Issues
 
 - If you are using HassOS and enable `check_known_hosts` without explicitly providing `known_hosts`, this may fail because the default known hosts file may not be accessible from within Home Assistant. Either disable host checking (not recommended) or provide `known_hosts` explicitly.

options_flow.py

@@ -75,6 +75,8 @@ async def validate_and_build_options(
                 user_input[CONF_HOST],
                 exit_status,
             )
+            if exit_status == 127:
+                return {}, "docker_command_not_found"
             return {}, "docker_command_failed"
     except ServiceValidationError as exc:
         translation_key = exc.translation_key if hasattr(exc, "translation_key") else "cannot_connect"
@@ -91,6 +93,23 @@ async def validate_and_build_options(
             exc,
         )
         return {}, "cannot_connect"
+    except FileNotFoundError as exc:
+        _LOGGER.warning(
+            "SSH validation for host %s raised FileNotFoundError: %s",
+            user_input[CONF_HOST],
+            exc,
+        )
+        from pathlib import Path
+
+        known_hosts = user_input.get(CONF_KNOWN_HOSTS) or "~/.ssh/known_hosts"
+        if (
+            user_input.get(CONF_CHECK_KNOWN_HOSTS, DEFAULT_CHECK_KNOWN_HOSTS)
+            and exc.filename is not None
+            and Path(exc.filename).expanduser().absolute()
+            == Path(known_hosts).expanduser().absolute()
+        ):
+            return {}, "known_hosts_not_found"
+        return {}, "cannot_connect"
     except Exception as exc:  # pylint: disable=broad-except
         _LOGGER.warning(
             "SSH validation for host %s raised an unexpected exception: %s",

strings.json

@@ -37,14 +37,17 @@
       }
     },
     "error": {
-      "password_or_key_file_required": "Either password or key file must be provided.",
-      "cannot_connect": "Cannot connect to the remote host.",
-      "docker_command_failed": "The docker command failed. Check the docker command and permissions.",
-      "host_key_not_verifiable": "The host key could not be verified.",
-      "login_failed": "SSH login failed. Check username and password/key file.",
-      "host_not_reachable": "Host is not reachable.",
-      "connection_timed_out": "Connection to the host timed out.",
-      "docker_service_not_found": "The service name was not found on the remote host. Check the name and make sure the container exists."
+      "password_or_key_file_required": "[E001] Either password or key file must be provided.",
+      "cannot_connect": "[E002] Cannot connect to the remote host.",
+      "docker_command_failed": "[E003] The docker command failed. Check that the docker command is correct, that the executable exists on the remote host (use its absolute path, especially with `sudo`), and that the user has permission to run it.",
+      "host_key_not_verifiable": "[E004] The host key could not be verified.",
+      "login_failed": "[E005] SSH login failed. Check username and password/key file.",
+      "host_not_reachable": "[E006] Host is not reachable.",
+      "connection_timed_out": "[E007] Connection to the host timed out.",
+      "docker_service_not_found": "[E008] The service name was not found on the remote host. Check the name and make sure the container exists.",
+      "docker_command_not_found": "[E009] The docker executable was not found on the remote host. Use the absolute path to the executable (e.g. /usr/bin/docker) or add it to the PATH of non-interactive SSH sessions.",
+      "known_hosts_not_found": "[E010] The known hosts file was not found. Provide the path to an existing known hosts file, create the default one (~/.ssh/known_hosts) on the Home Assistant machine, or disable 'Check Known Hosts'.",
+      "known_hosts_with_check_disabled": "[E011] The known hosts file was provided but 'Check Known Hosts' is disabled. Either enable 'Check Known Hosts' or remove the known hosts file path."
     },
     "abort": {
       "service_not_found": "The service ssh_command.execute was not found. Please install SSH Command through HACS and add it as an integration.",
@@ -85,13 +88,16 @@
       }
     },
     "error": {
-      "password_or_key_file_required": "Either password or key file must be provided.",
-      "cannot_connect": "Cannot connect to the remote host.",
-      "docker_command_failed": "The docker command failed. Check the docker command and permissions.",
-      "host_key_not_verifiable": "The host key could not be verified.",
-      "login_failed": "SSH login failed. Check username and password/key file.",
-      "host_not_reachable": "Host is not reachable.",
-      "connection_timed_out": "Connection to the host timed out."
+      "password_or_key_file_required": "[E001] Either password or key file must be provided.",
+      "cannot_connect": "[E002] Cannot connect to the remote host.",
+      "docker_command_failed": "[E003] The docker command failed. Check that the docker command is correct, that the executable exists on the remote host (use its absolute path, especially with `sudo`), and that the user has permission to run it.",
+      "host_key_not_verifiable": "[E004] The host key could not be verified.",
+      "login_failed": "[E005] SSH login failed. Check username and password/key file.",
+      "host_not_reachable": "[E006] Host is not reachable.",
+      "connection_timed_out": "[E007] Connection to the host timed out.",
+      "docker_command_not_found": "[E009] The docker executable was not found on the remote host. Use the absolute path to the executable (e.g. /usr/bin/docker) or add it to the PATH of non-interactive SSH sessions.",
+      "known_hosts_not_found": "[E010] The known hosts file was not found. Provide the path to an existing known hosts file, create the default one (~/.ssh/known_hosts) on the Home Assistant machine, or disable 'Check Known Hosts'.",
+      "known_hosts_with_check_disabled": "[E011] The known hosts file was provided but 'Check Known Hosts' is disabled. Either enable 'Check Known Hosts' or remove the known hosts file path."
     }
   },
   "services": {

translations/de.json

@@ -37,14 +37,17 @@
       }
     },
     "error": {
-      "password_or_key_file_required": "Es muss entweder ein Passwort oder eine Schlüsseldatei angegeben werden.",
-      "cannot_connect": "Es kann keine Verbindung zum entfernten Host hergestellt werden.",
-      "docker_command_failed": "Der Docker-Befehl ist fehlgeschlagen. Überprüfen Sie den Docker-Befehl und die Berechtigungen.",
-      "host_key_not_verifiable": "Der Host-Schlüssel konnte nicht verifiziert werden.",
-      "login_failed": "SSH-Anmeldung fehlgeschlagen. Überprüfen Sie Benutzername und Passwort/Schlüsseldatei.",
-      "host_not_reachable": "Host ist nicht erreichbar.",
-      "connection_timed_out": "Die Verbindung zum Host hat das Zeitlimit überschritten.",
-      "docker_service_not_found": "Der Dienstname wurde auf dem entfernten Host nicht gefunden. Überprüfen Sie den Namen und stellen Sie sicher, dass der Container existiert."
+      "password_or_key_file_required": "[E001] Es muss entweder ein Passwort oder eine Schlüsseldatei angegeben werden.",
+      "cannot_connect": "[E002] Es kann keine Verbindung zum entfernten Host hergestellt werden.",
+      "docker_command_failed": "[E003] Der Docker-Befehl ist fehlgeschlagen. Prüfen Sie, ob der Docker-Befehl korrekt ist, die ausführbare Datei auf dem entfernten Host existiert (verwenden Sie insbesondere mit `sudo` den absoluten Pfad) und der Benutzer sie ausführen darf.",
+      "host_key_not_verifiable": "[E004] Der Host-Schlüssel konnte nicht verifiziert werden.",
+      "login_failed": "[E005] SSH-Anmeldung fehlgeschlagen. Überprüfen Sie Benutzername und Passwort/Schlüsseldatei.",
+      "host_not_reachable": "[E006] Host ist nicht erreichbar.",
+      "connection_timed_out": "[E007] Die Verbindung zum Host hat das Zeitlimit überschritten.",
+      "docker_service_not_found": "[E008] Der Dienstname wurde auf dem entfernten Host nicht gefunden. Überprüfen Sie den Namen und stellen Sie sicher, dass der Container existiert.",
+      "docker_command_not_found": "[E009] Die ausführbare Docker-Datei wurde auf dem entfernten Host nicht gefunden. Verwenden Sie den absoluten Pfad zur Datei (z. B. /usr/bin/docker) oder fügen Sie sie dem PATH nicht-interaktiver SSH-Sitzungen hinzu.",
+      "known_hosts_not_found": "[E010] Die known_hosts-Datei wurde nicht gefunden. Geben Sie den Pfad zu einer vorhandenen known_hosts-Datei an, legen Sie die Standarddatei (~/.ssh/known_hosts) auf dem Home-Assistant-Rechner an oder deaktivieren Sie 'Bekannte Hosts prüfen'.",
+      "known_hosts_with_check_disabled": "[E011] Die known_hosts-Datei wurde angegeben, aber die Option 'Bekannte Hosts prüfen' ist deaktiviert. Entweder aktivieren Sie die Option oder entfernen Sie den Pfad zur known_hosts-Datei."
     },
     "abort": {
       "service_not_found": "Der Service ssh_command.execute wurde nicht gefunden. Bitte installiere SSH Command in HACS und füge die Integration hinzu.",
@@ -85,13 +88,16 @@
       }
     },
     "error": {
-      "password_or_key_file_required": "Es muss entweder ein Passwort oder eine Schlüsseldatei angegeben werden.",
-      "cannot_connect": "Es kann keine Verbindung zum entfernten Host hergestellt werden.",
-      "docker_command_failed": "Der Docker-Befehl ist fehlgeschlagen. Überprüfen Sie den Docker-Befehl und die Berechtigungen.",
-      "host_key_not_verifiable": "Der Host-Schlüssel konnte nicht verifiziert werden.",
-      "login_failed": "SSH-Anmeldung fehlgeschlagen. Überprüfen Sie Benutzername und Passwort/Schlüsseldatei.",
-      "host_not_reachable": "Host ist nicht erreichbar.",
-      "connection_timed_out": "Die Verbindung zum Host hat das Zeitlimit überschritten."
+      "password_or_key_file_required": "[E001] Es muss entweder ein Passwort oder eine Schlüsseldatei angegeben werden.",
+      "cannot_connect": "[E002] Es kann keine Verbindung zum entfernten Host hergestellt werden.",
+      "docker_command_failed": "[E003] Der Docker-Befehl ist fehlgeschlagen. Prüfen Sie, ob der Docker-Befehl korrekt ist, die ausführbare Datei auf dem entfernten Host existiert (verwenden Sie insbesondere mit `sudo` den absoluten Pfad) und der Benutzer sie ausführen darf.",
+      "host_key_not_verifiable": "[E004] Der Host-Schlüssel konnte nicht verifiziert werden.",
+      "login_failed": "[E005] SSH-Anmeldung fehlgeschlagen. Überprüfen Sie Benutzername und Passwort/Schlüsseldatei.",
+      "host_not_reachable": "[E006] Host ist nicht erreichbar.",
+      "connection_timed_out": "[E007] Die Verbindung zum Host hat das Zeitlimit überschritten.",
+      "docker_command_not_found": "[E009] Die ausführbare Docker-Datei wurde auf dem entfernten Host nicht gefunden. Verwenden Sie den absoluten Pfad zur Datei (z. B. /usr/bin/docker) oder fügen Sie sie dem PATH nicht-interaktiver SSH-Sitzungen hinzu.",
+      "known_hosts_not_found": "[E010] Die known_hosts-Datei wurde nicht gefunden. Geben Sie den Pfad zu einer vorhandenen known_hosts-Datei an, legen Sie die Standarddatei (~/.ssh/known_hosts) auf dem Home-Assistant-Rechner an oder deaktivieren Sie 'Bekannte Hosts prüfen'.",
+      "known_hosts_with_check_disabled": "[E011] Die known_hosts-Datei wurde angegeben, aber die Option 'Bekannte Hosts prüfen' ist deaktiviert. Entweder aktivieren Sie die Option oder entfernen Sie den Pfad zur known_hosts-Datei."
     }
   },
   "services": {