Add defined error for when build fails

supervisor/addons/addon.py

@@ -66,13 +66,22 @@ from ..docker.const import ContainerState
 from ..docker.monitor import DockerContainerStateEvent
 from ..docker.stats import DockerStats
 from ..exceptions import (
-    AddonConfigurationError,
+    AddonBackupMetadataInvalidError,
+    AddonBuildFailedUnknownError,
+    AddonConfigurationInvalidError,
+    AddonNotRunningError,
     AddonNotSupportedError,
+    AddonNotSupportedWriteStdinError,
+    AddonPrePostBackupCommandReturnedError,
     AddonsError,
     AddonsJobError,
+    AddonUnknownError,
+    BackupRestoreUnknownError,
     ConfigurationFileError,
+    DockerBuildError,
     DockerError,
     HostAppArmorError,
+    StoreAddonNotFoundError,
 )
 from ..hardware.data import Device
 from ..homeassistant.const import WSEvent
@@ -235,7 +244,7 @@ class Addon(AddonModel):
             await self.instance.check_image(self.version, default_image, self.arch)
         except DockerError:
             _LOGGER.info("No %s addon Docker image %s found", self.slug, self.image)
-            with suppress(DockerError):
+            with suppress(DockerError, AddonNotSupportedError):
                 await self.instance.install(self.version, default_image, arch=self.arch)
 
         self.persist[ATTR_IMAGE] = default_image
@@ -718,18 +727,16 @@ class Addon(AddonModel):
             options = self.schema.validate(self.options)
             await self.sys_run_in_executor(write_json_file, self.path_options, options)
         except vol.Invalid as ex:
-            _LOGGER.error(
+            raise AddonConfigurationInvalidError(
-                "Add-on %s has invalid options: %s",
+                _LOGGER.error,
-                self.slug,
+                addon=self.slug,
-                humanize_error(self.options, ex),
+                validation_error=humanize_error(self.options, ex),
-            )
+            ) from None
-        except ConfigurationFileError:
+        except ConfigurationFileError as err:
             _LOGGER.error("Add-on %s can't write options", self.slug)
-        else:
+            raise AddonUnknownError(addon=self.slug) from err
-            _LOGGER.debug("Add-on %s write options: %s", self.slug, options)
-            return
 
-        raise AddonConfigurationError()
+        _LOGGER.debug("Add-on %s write options: %s", self.slug, options)
 
     @Job(
         name="addon_unload",
@@ -772,7 +779,7 @@ class Addon(AddonModel):
     async def install(self) -> None:
         """Install and setup this addon."""
         if not self.addon_store:
-            raise AddonsError("Missing from store, cannot install!")
+            raise StoreAddonNotFoundError(addon=self.slug)
 
         await self.sys_addons.data.install(self.addon_store)
 
@@ -793,9 +800,17 @@ class Addon(AddonModel):
             await self.instance.install(
                 self.latest_version, self.addon_store.image, arch=self.arch
             )
-        except DockerError as err:
+        except AddonsError:
             await self.sys_addons.data.uninstall(self)
-            raise AddonsError() from err
+            raise
+        except DockerBuildError as err:
+            _LOGGER.error("Could not build image for addon %s: %s", self.slug, err)
+            await self.sys_addons.data.uninstall(self)
+            raise AddonBuildFailedUnknownError(addon=self.slug) from err
+        except DockerError as err:
+            _LOGGER.error("Could not pull image to update addon %s: %s", self.slug, err)
+            await self.sys_addons.data.uninstall(self)
+            raise AddonUnknownError(addon=self.slug) from err
 
         # Finish initialization and set up listeners
         await self.load()
@@ -819,7 +834,8 @@ class Addon(AddonModel):
         try:
             await self.instance.remove(remove_image=remove_image)
         except DockerError as err:
-            raise AddonsError() from err
+            _LOGGER.error("Could not remove image for addon %s: %s", self.slug, err)
+            raise AddonUnknownError(addon=self.slug) from err
 
         self.state = AddonState.UNKNOWN
 
@@ -884,7 +900,7 @@ class Addon(AddonModel):
         if it was running. Else nothing is returned.
         """
         if not self.addon_store:
-            raise AddonsError("Missing from store, cannot update!")
+            raise StoreAddonNotFoundError(addon=self.slug)
 
         old_image = self.image
         # Cache data to prevent races with other updates to global
@@ -892,8 +908,12 @@ class Addon(AddonModel):
 
         try:
             await self.instance.update(store.version, store.image, arch=self.arch)
+        except DockerBuildError as err:
+            _LOGGER.error("Could not build image for addon %s: %s", self.slug, err)
+            raise AddonBuildFailedUnknownError(addon=self.slug) from err
         except DockerError as err:
-            raise AddonsError() from err
+            _LOGGER.error("Could not pull image to update addon %s: %s", self.slug, err)
+            raise AddonUnknownError(addon=self.slug) from err
 
         # Stop the addon if running
         if (last_state := self.state) in {AddonState.STARTED, AddonState.STARTUP}:
@@ -935,12 +955,23 @@ class Addon(AddonModel):
         """
         last_state: AddonState = self.state
         try:
-            # remove docker container but not addon config
+            # remove docker container and image but not addon config
             try:
                 await self.instance.remove()
-                await self.instance.install(self.version)
             except DockerError as err:
-                raise AddonsError() from err
+                _LOGGER.error("Could not remove image for addon %s: %s", self.slug, err)
+                raise AddonUnknownError(addon=self.slug) from err
+
+            try:
+                await self.instance.install(self.version)
+            except DockerBuildError as err:
+                _LOGGER.error("Could not build image for addon %s: %s", self.slug, err)
+                raise AddonBuildFailedUnknownError(addon=self.slug) from err
+            except DockerError as err:
+                _LOGGER.error(
+                    "Could not pull image to update addon %s: %s", self.slug, err
+                )
+                raise AddonUnknownError(addon=self.slug) from err
 
             if self.addon_store:
                 await self.sys_addons.data.update(self.addon_store)
@@ -1111,8 +1142,9 @@ class Addon(AddonModel):
         try:
             await self.instance.run()
         except DockerError as err:
+            _LOGGER.error("Could not start container for addon %s: %s", self.slug, err)
             self.state = AddonState.ERROR
-            raise AddonsError() from err
+            raise AddonUnknownError(addon=self.slug) from err
 
         return self.sys_create_task(self._wait_for_startup())
 
@@ -1127,8 +1159,9 @@ class Addon(AddonModel):
         try:
             await self.instance.stop()
         except DockerError as err:
+            _LOGGER.error("Could not stop container for addon %s: %s", self.slug, err)
             self.state = AddonState.ERROR
-            raise AddonsError() from err
+            raise AddonUnknownError(addon=self.slug) from err
 
     @Job(
         name="addon_restart",
@@ -1161,9 +1194,15 @@ class Addon(AddonModel):
     async def stats(self) -> DockerStats:
         """Return stats of container."""
         try:
+            if not await self.is_running():
+                raise AddonNotRunningError(_LOGGER.warning, addon=self.slug)
+
             return await self.instance.stats()
         except DockerError as err:
-            raise AddonsError() from err
+            _LOGGER.error(
+                "Could not get stats of container for addon %s: %s", self.slug, err
+            )
+            raise AddonUnknownError(addon=self.slug) from err
 
     @Job(
         name="addon_write_stdin",
@@ -1173,14 +1212,18 @@ class Addon(AddonModel):
     async def write_stdin(self, data) -> None:
         """Write data to add-on stdin."""
         if not self.with_stdin:
-            raise AddonNotSupportedError(
+            raise AddonNotSupportedWriteStdinError(_LOGGER.error, addon=self.slug)
-                f"Add-on {self.slug} does not support writing to stdin!", _LOGGER.error
-            )
 
         try:
-            return await self.instance.write_stdin(data)
+            if not await self.is_running():
+                raise AddonNotRunningError(_LOGGER.warning, addon=self.slug)
+
+            await self.instance.write_stdin(data)
         except DockerError as err:
-            raise AddonsError() from err
+            _LOGGER.error(
+                "Could not write stdin to container for addon %s: %s", self.slug, err
+            )
+            raise AddonUnknownError(addon=self.slug) from err
 
     async def _backup_command(self, command: str) -> None:
         try:
@@ -1189,15 +1232,14 @@ class Addon(AddonModel):
                 _LOGGER.debug(
                     "Pre-/Post backup command failed with: %s", command_return.output
                 )
-                raise AddonsError(
+                raise AddonPrePostBackupCommandReturnedError(
-                    f"Pre-/Post backup command returned error code: {command_return.exit_code}",
+                    _LOGGER.error, addon=self.slug, exit_code=command_return.exit_code
-                    _LOGGER.error,
                 )
         except DockerError as err:
-            raise AddonsError(
+            _LOGGER.error(
-                f"Failed running pre-/post backup command {command}: {str(err)}",
+                "Failed running pre-/post backup command %s: %s", command, err
-                _LOGGER.error,
+            )
-            ) from err
+            raise AddonUnknownError(addon=self.slug) from err
 
     @Job(
         name="addon_begin_backup",
@@ -1286,15 +1328,14 @@ class Addon(AddonModel):
                     try:
                         self.instance.export_image(temp_path.joinpath("image.tar"))
                     except DockerError as err:
-                        raise AddonsError() from err
+                        raise BackupRestoreUnknownError() from err
 
                 # Store local configs/state
                 try:
                     write_json_file(temp_path.joinpath("addon.json"), metadata)
                 except ConfigurationFileError as err:
-                    raise AddonsError(
+                    _LOGGER.error("Can't save meta for %s: %s", self.slug, err)
-                        f"Can't save meta for {self.slug}", _LOGGER.error
+                    raise BackupRestoreUnknownError() from err
-                    ) from err
 
                 # Store AppArmor Profile
                 if apparmor_profile:
@@ -1304,9 +1345,7 @@ class Addon(AddonModel):
                             apparmor_profile, profile_backup_file
                         )
                     except HostAppArmorError as err:
-                        raise AddonsError(
+                        raise BackupRestoreUnknownError() from err
-                            "Can't backup AppArmor profile", _LOGGER.error
-                        ) from err
 
                 # Write tarfile
                 with tar_file as backup:
@@ -1360,7 +1399,8 @@ class Addon(AddonModel):
             )
             _LOGGER.info("Finish backup for addon %s", self.slug)
         except (tarfile.TarError, OSError, AddFileError) as err:
-            raise AddonsError(f"Can't write tarfile: {err}", _LOGGER.error) from err
+            _LOGGER.error("Can't write backup tarfile for addon %s: %s", self.slug, err)
+            raise BackupRestoreUnknownError() from err
         finally:
             if was_running:
                 wait_for_start = await self.end_backup()
@@ -1402,28 +1442,24 @@ class Addon(AddonModel):
         try:
             tmp, data = await self.sys_run_in_executor(_extract_tarfile)
         except tarfile.TarError as err:
-            raise AddonsError(
+            _LOGGER.error("Can't extract backup tarfile for %s: %s", self.slug, err)
-                f"Can't read tarfile {tar_file}: {err}", _LOGGER.error
+            raise BackupRestoreUnknownError() from err
-            ) from err
         except ConfigurationFileError as err:
-            raise AddonsError() from err
+            raise AddonUnknownError(addon=self.slug) from err
 
         try:
             # Validate
             try:
                 data = SCHEMA_ADDON_BACKUP(data)
             except vol.Invalid as err:
-                raise AddonsError(
+                raise AddonBackupMetadataInvalidError(
-                    f"Can't validate {self.slug}, backup data: {humanize_error(data, err)}",
                     _LOGGER.error,
+                    addon=self.slug,
+                    validation_error=humanize_error(data, err),
                 ) from err
 
-            # If available
+            # Validate availability. Raises if not
-            if not self._available(data[ATTR_SYSTEM]):
+            self._validate_availability(data[ATTR_SYSTEM], logger=_LOGGER.error)
-                raise AddonNotSupportedError(
-                    f"Add-on {self.slug} is not available for this platform",
-                    _LOGGER.error,
-                )
 
             # Restore local add-on information
             _LOGGER.info("Restore config for addon %s", self.slug)
@@ -1482,9 +1518,10 @@ class Addon(AddonModel):
                 try:
                     await self.sys_run_in_executor(_restore_data)
                 except shutil.Error as err:
-                    raise AddonsError(
+                    _LOGGER.error(
-                        f"Can't restore origin data: {err}", _LOGGER.error
+                        "Can't restore origin data for %s: %s", self.slug, err
-                    ) from err
+                    )
+                    raise BackupRestoreUnknownError() from err
 
                 # Restore AppArmor
                 profile_file = Path(tmp.name, "apparmor.txt")
@@ -1495,10 +1532,11 @@ class Addon(AddonModel):
                         )
                     except HostAppArmorError as err:
                         _LOGGER.error(
-                            "Can't restore AppArmor profile for add-on %s",
+                            "Can't restore AppArmor profile for add-on %s: %s",
                             self.slug,
+                            err,
                         )
-                        raise AddonsError() from err
+                        raise BackupRestoreUnknownError() from err
 
             finally:
                 # Is add-on loaded

supervisor/addons/build.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from functools import cached_property
+import logging
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
@@ -19,13 +20,20 @@ from ..const import (
 )
 from ..coresys import CoreSys, CoreSysAttributes
 from ..docker.interface import MAP_ARCH
-from ..exceptions import ConfigurationFileError, HassioArchNotFound
+from ..exceptions import (
+    AddonBuildArchitectureNotSupportedError,
+    AddonBuildDockerfileMissingError,
+    ConfigurationFileError,
+    HassioArchNotFound,
+)
 from ..utils.common import FileConfiguration, find_one_filetype
 from .validate import SCHEMA_BUILD_CONFIG
 
 if TYPE_CHECKING:
     from .manager import AnyAddon
 
+_LOGGER: logging.Logger = logging.getLogger(__name__)
+
 
 class AddonBuild(FileConfiguration, CoreSysAttributes):
     """Handle build options for add-ons."""
@@ -106,7 +114,7 @@ class AddonBuild(FileConfiguration, CoreSysAttributes):
             return self.addon.path_location.joinpath(f"Dockerfile.{self.arch}")
         return self.addon.path_location.joinpath("Dockerfile")
 
-    async def is_valid(self) -> bool:
+    async def is_valid(self) -> None:
         """Return true if the build env is valid."""
 
         def build_is_valid() -> bool:
@@ -118,9 +126,17 @@ class AddonBuild(FileConfiguration, CoreSysAttributes):
             )
 
         try:
-            return await self.sys_run_in_executor(build_is_valid)
+            if not await self.sys_run_in_executor(build_is_valid):
+                raise AddonBuildDockerfileMissingError(
+                    _LOGGER.error, addon=self.addon.slug
+                )
         except HassioArchNotFound:
-            return False
+            raise AddonBuildArchitectureNotSupportedError(
+                _LOGGER.error,
+                addon=self.addon.slug,
+                addon_arch_list=self.addon.supported_arch,
+                system_arch_list=self.sys_arch.supported,
+            ) from None
 
     def get_docker_args(
         self, version: AwesomeVersion, image_tag: str

supervisor/api/addons.py

@@ -100,6 +100,9 @@ from ..const import (
 from ..coresys import CoreSysAttributes
 from ..docker.stats import DockerStats
 from ..exceptions import (
+    AddonBootConfigCannotChangeError,
+    AddonConfigurationInvalidError,
+    AddonNotSupportedWriteStdinError,
     APIAddonNotInstalled,
     APIError,
     APIForbidden,
@@ -125,6 +128,7 @@ SCHEMA_OPTIONS = vol.Schema(
         vol.Optional(ATTR_AUDIO_INPUT): vol.Maybe(str),
         vol.Optional(ATTR_INGRESS_PANEL): vol.Boolean(),
         vol.Optional(ATTR_WATCHDOG): vol.Boolean(),
+        vol.Optional(ATTR_OPTIONS): vol.Maybe(dict),
     }
 )
 
@@ -300,19 +304,20 @@ class APIAddons(CoreSysAttributes):
         # Update secrets for validation
         await self.sys_homeassistant.secrets.reload()
 
-        # Extend schema with add-on specific validation
-        addon_schema = SCHEMA_OPTIONS.extend(
-            {vol.Optional(ATTR_OPTIONS): vol.Maybe(addon.schema)}
-        )
-
         # Validate/Process Body
-        body = await api_validate(addon_schema, request)
+        body = await api_validate(SCHEMA_OPTIONS, request)
         if ATTR_OPTIONS in body:
-            addon.options = body[ATTR_OPTIONS]
+            try:
+                addon.options = addon.schema(body[ATTR_OPTIONS])
+            except vol.Invalid as ex:
+                raise AddonConfigurationInvalidError(
+                    addon=addon.slug,
+                    validation_error=humanize_error(body[ATTR_OPTIONS], ex),
+                ) from None
         if ATTR_BOOT in body:
             if addon.boot_config == AddonBootConfig.MANUAL_ONLY:
-                raise APIError(
+                raise AddonBootConfigCannotChangeError(
-                    f"Addon {addon.slug} boot option is set to {addon.boot_config} so it cannot be changed"
+                    addon=addon.slug, boot_config=addon.boot_config.value
                 )
             addon.boot = body[ATTR_BOOT]
         if ATTR_AUTO_UPDATE in body:
@@ -476,7 +481,7 @@ class APIAddons(CoreSysAttributes):
         """Write to stdin of add-on."""
         addon = self.get_addon_for_request(request)
         if not addon.with_stdin:
-            raise APIError(f"STDIN not supported the {addon.slug} add-on")
+            raise AddonNotSupportedWriteStdinError(_LOGGER.error, addon=addon.slug)
 
         data = await request.read()
         await asyncio.shield(addon.write_stdin(data))

supervisor/api/auth.py

@@ -15,7 +15,7 @@ import voluptuous as vol
 from ..addons.addon import Addon
 from ..const import ATTR_NAME, ATTR_PASSWORD, ATTR_USERNAME, REQUEST_FROM
 from ..coresys import CoreSysAttributes
-from ..exceptions import APIForbidden
+from ..exceptions import APIForbidden, AuthInvalidNonStringValueError
 from .const import (
     ATTR_GROUP_IDS,
     ATTR_IS_ACTIVE,
@@ -69,7 +69,9 @@ class APIAuth(CoreSysAttributes):
         try:
             _ = username.encode and password.encode  # type: ignore
         except AttributeError:
-            raise HTTPUnauthorized(headers=REALM_HEADER) from None
+            raise AuthInvalidNonStringValueError(
+                _LOGGER.error, headers=REALM_HEADER
+            ) from None
 
         return self.sys_auth.check_login(
             addon, cast(str, username), cast(str, password)

supervisor/api/store.py

@@ -53,7 +53,7 @@ from ..const import (
     REQUEST_FROM,
 )
 from ..coresys import CoreSysAttributes
-from ..exceptions import APIError, APIForbidden, APINotFound
+from ..exceptions import APIError, APIForbidden, APINotFound, StoreAddonNotFoundError
 from ..store.addon import AddonStore
 from ..store.repository import Repository
 from ..store.validate import validate_repository
@@ -104,7 +104,7 @@ class APIStore(CoreSysAttributes):
         addon_slug: str = request.match_info["addon"]
 
         if not (addon := self.sys_addons.get(addon_slug)):
-            raise APINotFound(f"Addon {addon_slug} does not exist")
+            raise StoreAddonNotFoundError(addon=addon_slug)
 
         if installed and not addon.is_installed:
             raise APIError(f"Addon {addon_slug} is not installed")
@@ -112,7 +112,7 @@ class APIStore(CoreSysAttributes):
         if not installed and addon.is_installed:
             addon = cast(Addon, addon)
             if not addon.addon_store:
-                raise APINotFound(f"Addon {addon_slug} does not exist in the store")
+                raise StoreAddonNotFoundError(addon=addon_slug)
             return addon.addon_store
 
         return addon

supervisor/api/utils.py

@@ -1,7 +1,7 @@
 """Init file for Supervisor util for RESTful API."""
 
 import asyncio
-from collections.abc import Callable
+from collections.abc import Callable, Mapping
 import json
 from typing import Any, cast
 
@@ -26,7 +26,7 @@ from ..const import (
     RESULT_OK,
 )
 from ..coresys import CoreSys, CoreSysAttributes
-from ..exceptions import APIError, BackupFileNotFoundError, DockerAPIError, HassioError
+from ..exceptions import APIError, DockerAPIError, HassioError
 from ..jobs import JobSchedulerOptions, SupervisorJob
 from ..utils import check_exception_chain, get_message_from_exception_chain
 from ..utils.json import json_dumps, json_loads as json_loads_util
@@ -69,10 +69,10 @@ def api_process(method):
         """Return API information."""
         try:
             answer = await method(api, *args, **kwargs)
-        except BackupFileNotFoundError as err:
-            return api_return_error(err, status=404)
         except APIError as err:
-            return api_return_error(err, status=err.status, job_id=err.job_id)
+            return api_return_error(
+                err, status=err.status, job_id=err.job_id, headers=err.headers
+            )
         except HassioError as err:
             return api_return_error(err)
 
@@ -143,6 +143,7 @@ def api_return_error(
     error_type: str | None = None,
     status: int = 400,
     *,
+    headers: Mapping[str, str] | None = None,
     job_id: str | None = None,
 ) -> web.Response:
     """Return an API error message."""
@@ -155,10 +156,15 @@ def api_return_error(
 
     match error_type:
         case const.CONTENT_TYPE_TEXT:
-            return web.Response(body=message, content_type=error_type, status=status)
+            return web.Response(
+                body=message, content_type=error_type, status=status, headers=headers
+            )
         case const.CONTENT_TYPE_BINARY:
             return web.Response(
-                body=message.encode(), content_type=error_type, status=status
+                body=message.encode(),
+                content_type=error_type,
+                status=status,
+                headers=headers,
             )
         case _:
             result: dict[str, Any] = {
@@ -176,6 +182,7 @@ def api_return_error(
         result,
         status=status,
         dumps=json_dumps,
+        headers=headers,
     )
 
 

supervisor/auth.py

@@ -9,8 +9,10 @@ from .addons.addon import Addon
 from .const import ATTR_PASSWORD, ATTR_TYPE, ATTR_USERNAME, FILE_HASSIO_AUTH
 from .coresys import CoreSys, CoreSysAttributes
 from .exceptions import (
-    AuthError,
+    AuthHomeAssistantAPIValidationError,
+    AuthInvalidNonStringValueError,
     AuthListUsersError,
+    AuthListUsersNoneResponseError,
     AuthPasswordResetError,
     HomeAssistantAPIError,
     HomeAssistantWSError,
@@ -83,10 +85,8 @@ class Auth(FileConfiguration, CoreSysAttributes):
         self, addon: Addon, username: str | None, password: str | None
     ) -> bool:
         """Check username login."""
-        if password is None:
+        if username is None or password is None:
-            raise AuthError("None as password is not supported!", _LOGGER.error)
+            raise AuthInvalidNonStringValueError(_LOGGER.error)
-        if username is None:
-            raise AuthError("None as username is not supported!", _LOGGER.error)
 
         _LOGGER.info("Auth request from '%s' for '%s'", addon.slug, username)
 
@@ -137,7 +137,7 @@ class Auth(FileConfiguration, CoreSysAttributes):
         finally:
             self._running.pop(username, None)
 
-        raise AuthError()
+        raise AuthHomeAssistantAPIValidationError()
 
     async def change_password(self, username: str, password: str) -> None:
         """Change user password login."""
@@ -155,7 +155,7 @@ class Auth(FileConfiguration, CoreSysAttributes):
         except HomeAssistantAPIError as err:
             _LOGGER.error("Can't request password reset on Home Assistant: %s", err)
 
-        raise AuthPasswordResetError()
+        raise AuthPasswordResetError(user=username)
 
     async def list_users(self) -> list[dict[str, Any]]:
         """List users on the Home Assistant instance."""
@@ -166,15 +166,12 @@ class Auth(FileConfiguration, CoreSysAttributes):
                 {ATTR_TYPE: "config/auth/list"}
             )
         except HomeAssistantWSError as err:
-            raise AuthListUsersError(
+            _LOGGER.error("Can't request listing users on Home Assistant: %s", err)
-                f"Can't request listing users on Home Assistant: {err}", _LOGGER.error
+            raise AuthListUsersError() from err
-            ) from err
 
         if users is not None:
             return users
-        raise AuthListUsersError(
+        raise AuthListUsersNoneResponseError(_LOGGER.error)
-            "Can't request listing users on Home Assistant!", _LOGGER.error
-        )
 
     @staticmethod
     def _rehash(value: str, salt2: str = "") -> str:

supervisor/backups/backup.py

@@ -628,9 +628,6 @@ class Backup(JobGroup):
                 if start_task := await self._addon_save(addon):
                     start_tasks.append(start_task)
             except BackupError as err:
-                err = BackupError(
-                    f"Can't backup add-on {addon.slug}: {str(err)}", _LOGGER.error
-                )
                 self.sys_jobs.current.capture_error(err)
 
         return start_tasks

supervisor/docker/addon.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from collections.abc import Awaitable
 from contextlib import suppress
 from ipaddress import IPv4Address
 import logging
@@ -33,6 +34,7 @@ from ..coresys import CoreSys
 from ..exceptions import (
     CoreDNSError,
     DBusError,
+    DockerBuildError,
     DockerError,
     DockerJobError,
     DockerNotFound,
@@ -680,9 +682,8 @@ class DockerAddon(DockerInterface):
     async def _build(self, version: AwesomeVersion, image: str | None = None) -> None:
         """Build a Docker container."""
         build_env = await AddonBuild(self.coresys, self.addon).load_config()
-        if not await build_env.is_valid():
+        # Check if the build environment is valid, raises if not
-            _LOGGER.error("Invalid build environment, can't build this add-on!")
+        await build_env.is_valid()
-            raise DockerError()
 
         _LOGGER.info("Starting build for %s:%s", self.image, version)
 
@@ -733,8 +734,9 @@ class DockerAddon(DockerInterface):
             requests.RequestException,
             aiodocker.DockerError,
         ) as err:
-            _LOGGER.error("Can't build %s:%s: %s", self.image, version, err)
+            raise DockerBuildError(
-            raise DockerError() from err
+                f"Can't build {self.image}:{version}: {err!s}", _LOGGER.error
+            ) from err
 
         _LOGGER.info("Build %s:%s done", self.image, version)
 
@@ -792,12 +794,9 @@ class DockerAddon(DockerInterface):
         on_condition=DockerJobError,
         concurrency=JobConcurrency.GROUP_REJECT,
     )
-    async def write_stdin(self, data: bytes) -> None:
+    def write_stdin(self, data: bytes) -> Awaitable[None]:
         """Write to add-on stdin."""
-        if not await self.is_running():
+        return self.sys_run_in_executor(self._write_stdin, data)
-            raise DockerError()
-
-        await self.sys_run_in_executor(self._write_stdin, data)
 
     def _write_stdin(self, data: bytes) -> None:
         """Write to add-on stdin.

supervisor/docker/interface.py

@@ -482,35 +482,34 @@ class DockerInterface(JobGroup, ABC):
             return True
         return False
 
-    async def is_running(self) -> bool:
+    async def _get_container(self) -> Container | None:
-        """Return True if Docker is running."""
+        """Get docker container, returns None if not found."""
         try:
-            docker_container = await self.sys_run_in_executor(
+            return await self.sys_run_in_executor(
                 self.sys_docker.containers.get, self.name
             )
         except docker.errors.NotFound:
-            return False
+            return None
         except docker.errors.DockerException as err:
-            raise DockerAPIError() from err
+            raise DockerAPIError(
+                f"Docker API error occurred while getting container information: {err!s}"
+            ) from err
         except requests.RequestException as err:
-            raise DockerRequestError() from err
+            raise DockerRequestError(
+                f"Error communicating with Docker to get container information: {err!s}"
+            ) from err
 
+    async def is_running(self) -> bool:
+        """Return True if Docker is running."""
+        if docker_container := await self._get_container():
             return docker_container.status == "running"
+        return False
 
     async def current_state(self) -> ContainerState:
         """Return current state of container."""
-        try:
+        if docker_container := await self._get_container():
-            docker_container = await self.sys_run_in_executor(
-                self.sys_docker.containers.get, self.name
-            )
-        except docker.errors.NotFound:
-            return ContainerState.UNKNOWN
-        except docker.errors.DockerException as err:
-            raise DockerAPIError() from err
-        except requests.RequestException as err:
-            raise DockerRequestError() from err
-
             return _container_state_from_model(docker_container)
+        return ContainerState.UNKNOWN
 
     @Job(name="docker_interface_attach", concurrency=JobConcurrency.GROUP_QUEUE)
     async def attach(
@@ -545,7 +544,9 @@ class DockerInterface(JobGroup, ABC):
 
         # Successful?
         if not self._meta:
-            raise DockerError()
+            raise DockerError(
+                f"Could not get metadata on container or image for {self.name}"
+            )
         _LOGGER.info("Attaching to %s with version %s", self.image, self.version)
 
     @Job(
@@ -750,14 +751,8 @@ class DockerInterface(JobGroup, ABC):
 
     async def is_failed(self) -> bool:
         """Return True if Docker is failing state."""
-        try:
+        if not (docker_container := await self._get_container()):
-            docker_container = await self.sys_run_in_executor(
-                self.sys_docker.containers.get, self.name
-            )
-        except docker.errors.NotFound:
             return False
-        except (docker.errors.DockerException, requests.RequestException) as err:
-            raise DockerError() from err
 
         # container is not running
         if docker_container.status != "exited":

supervisor/docker/manager.py

@@ -578,9 +578,15 @@ class DockerAPI(CoreSysAttributes):
         except aiodocker.DockerError as err:
             if err.status == HTTPStatus.NOT_FOUND:
                 return False
-            raise DockerError() from err
+            raise DockerError(
+                f"Could not get container {name} or image {image}:{version} to check state: {err!s}",
+                _LOGGER.error,
+            ) from err
         except (docker_errors.DockerException, requests.RequestException) as err:
-            raise DockerError() from err
+            raise DockerError(
+                f"Could not get container {name} or image {image}:{version} to check state: {err!s}",
+                _LOGGER.error,
+            ) from err
 
         # Check the image is correct and state is good
         return (
@@ -596,9 +602,13 @@ class DockerAPI(CoreSysAttributes):
         try:
             docker_container: Container = self.containers.get(name)
         except docker_errors.NotFound:
+            # Generally suppressed so we don't log this
             raise DockerNotFound() from None
         except (docker_errors.DockerException, requests.RequestException) as err:
-            raise DockerError() from err
+            raise DockerError(
+                f"Could not get container {name} for stopping: {err!s}",
+                _LOGGER.error,
+            ) from err
 
         if docker_container.status == "running":
             _LOGGER.info("Stopping %s application", name)
@@ -638,9 +648,13 @@ class DockerAPI(CoreSysAttributes):
         try:
             container: Container = self.containers.get(name)
         except docker_errors.NotFound:
-            raise DockerNotFound() from None
+            raise DockerNotFound(
+                f"Container {name} not found for restarting", _LOGGER.warning
+            ) from None
         except (docker_errors.DockerException, requests.RequestException) as err:
-            raise DockerError() from err
+            raise DockerError(
+                f"Could not get container {name} for restarting: {err!s}", _LOGGER.error
+            ) from err
 
         _LOGGER.info("Restarting %s", name)
         try:
@@ -653,9 +667,13 @@ class DockerAPI(CoreSysAttributes):
         try:
             docker_container: Container = self.containers.get(name)
         except docker_errors.NotFound:
-            raise DockerNotFound() from None
+            raise DockerNotFound(
+                f"Container {name} not found for logs", _LOGGER.warning
+            ) from None
         except (docker_errors.DockerException, requests.RequestException) as err:
-            raise DockerError() from err
+            raise DockerError(
+                f"Could not get container {name} for logs: {err!s}", _LOGGER.error
+            ) from err
 
         try:
             return docker_container.logs(tail=tail, stdout=True, stderr=True)
@@ -669,9 +687,13 @@ class DockerAPI(CoreSysAttributes):
         try:
             docker_container: Container = self.containers.get(name)
         except docker_errors.NotFound:
-            raise DockerNotFound() from None
+            raise DockerNotFound(
+                f"Container {name} not found for stats", _LOGGER.warning
+            ) from None
         except (docker_errors.DockerException, requests.RequestException) as err:
-            raise DockerError() from err
+            raise DockerError(
+                f"Could not inspect container '{name}': {err!s}", _LOGGER.error
+            ) from err
 
         # container is not running
         if docker_container.status != "running":
@@ -689,15 +711,21 @@ class DockerAPI(CoreSysAttributes):
         try:
             docker_container: Container = self.containers.get(name)
         except docker_errors.NotFound:
-            raise DockerNotFound() from None
+            raise DockerNotFound(
+                f"Container {name} not found for running command", _LOGGER.warning
+            ) from None
         except (docker_errors.DockerException, requests.RequestException) as err:
-            raise DockerError() from err
+            raise DockerError(
+                f"Can't get container {name} to run command: {err!s}"
+            ) from err
 
         # Execute
         try:
             code, output = docker_container.exec_run(command)
         except (docker_errors.DockerException, requests.RequestException) as err:
-            raise DockerError() from err
+            raise DockerError(
+                f"Can't run command in container {name}: {err!s}"
+            ) from err
 
         return CommandReturn(code, output)
 

supervisor/exceptions.py

@@ -1,25 +1,25 @@
 """Core Exceptions."""
 
-from collections.abc import Callable
+from collections.abc import Callable, Mapping
 from typing import Any
 
+MESSAGE_CHECK_SUPERVISOR_LOGS = (
+    "Check supervisor logs for details (check with '{logs_command}')"
+)
+EXTRA_FIELDS_LOGS_COMMAND = {"logs_command": "ha supervisor logs"}
+
 
 class HassioError(Exception):
     """Root exception."""
 
     error_key: str | None = None
     message_template: str | None = None
+    extra_fields: dict[str, Any] | None = None
 
     def __init__(
-        self,
+        self, message: str | None = None, logger: Callable[..., None] | None = None
-        message: str | None = None,
-        logger: Callable[..., None] | None = None,
-        *,
-        extra_fields: dict[str, Any] | None = None,
     ) -> None:
         """Raise & log."""
-        self.extra_fields = extra_fields or {}
-
         if not message and self.message_template:
             message = (
                 self.message_template.format(**self.extra_fields)
@@ -41,6 +41,94 @@ class HassioNotSupportedError(HassioError):
     """Function is not supported."""
 
 
+# API
+
+
+class APIError(HassioError, RuntimeError):
+    """API errors."""
+
+    status = 400
+    headers: Mapping[str, str] | None = None
+
+    def __init__(
+        self,
+        message: str | None = None,
+        logger: Callable[..., None] | None = None,
+        *,
+        headers: Mapping[str, str] | None = None,
+        job_id: str | None = None,
+    ) -> None:
+        """Raise & log, optionally with job."""
+        super().__init__(message, logger)
+        self.headers = headers
+        self.job_id = job_id
+
+
+class APIUnauthorized(APIError):
+    """API unauthorized error."""
+
+    status = 401
+
+
+class APIForbidden(APIError):
+    """API forbidden error."""
+
+    status = 403
+
+
+class APINotFound(APIError):
+    """API not found error."""
+
+    status = 404
+
+
+class APIGone(APIError):
+    """API is no longer available."""
+
+    status = 410
+
+
+class APITooManyRequests(APIError):
+    """API too many requests error."""
+
+    status = 429
+
+
+class APIInternalServerError(APIError):
+    """API internal server error."""
+
+    status = 500
+
+
+class APIAddonNotInstalled(APIError):
+    """Not installed addon requested at addons API."""
+
+
+class APIDBMigrationInProgress(APIError):
+    """Service is unavailable due to an offline DB migration is in progress."""
+
+    status = 503
+
+
+class APIUnknownSupervisorError(APIError):
+    """Unknown error occurred within supervisor. Adds supervisor check logs rider to mesage template."""
+
+    status = 500
+
+    def __init__(
+        self,
+        logger: Callable[..., None] | None = None,
+        *,
+        job_id: str | None = None,
+    ) -> None:
+        """Initialize exception."""
+        self.message_template = (
+            f"{self.message_template}. {MESSAGE_CHECK_SUPERVISOR_LOGS}"
+        )
+        self.extra_fields = (self.extra_fields or {}) | EXTRA_FIELDS_LOGS_COMMAND
+        super().__init__(None, logger, job_id=job_id)
+
+
 # JobManager
 
 
@@ -122,6 +210,13 @@ class SupervisorAppArmorError(SupervisorError):
     """Supervisor AppArmor error."""
 
 
+class SupervisorUnknownError(SupervisorError, APIUnknownSupervisorError):
+    """Raise when an unknown error occurs interacting with Supervisor or its container."""
+
+    error_key = "supervisor_unknown_error"
+    message_template = "An unknown error occurred with Supervisor"
+
+
 class SupervisorJobError(SupervisorError, JobException):
     """Raise on job errors."""
 
@@ -250,6 +345,54 @@ class AddonConfigurationError(AddonsError):
     """Error with add-on configuration."""
 
 
+class AddonConfigurationInvalidError(AddonConfigurationError, APIError):
+    """Raise if invalid configuration provided for addon."""
+
+    error_key = "addon_configuration_invalid_error"
+    message_template = "Add-on {addon} has invalid options: {validation_error}"
+
+    def __init__(
+        self,
+        logger: Callable[..., None] | None = None,
+        *,
+        addon: str,
+        validation_error: str,
+    ) -> None:
+        """Initialize exception."""
+        self.extra_fields = {"addon": addon, "validation_error": validation_error}
+        super().__init__(None, logger)
+
+
+class AddonBootConfigCannotChangeError(AddonsError, APIError):
+    """Raise if user attempts to change addon boot config when it can't be changed."""
+
+    error_key = "addon_boot_config_cannot_change_error"
+    message_template = (
+        "Addon {addon} boot option is set to {boot_config} so it cannot be changed"
+    )
+
+    def __init__(
+        self, logger: Callable[..., None] | None = None, *, addon: str, boot_config: str
+    ) -> None:
+        """Initialize exception."""
+        self.extra_fields = {"addon": addon, "boot_config": boot_config}
+        super().__init__(None, logger)
+
+
+class AddonNotRunningError(AddonsError, APIError):
+    """Raise when an addon is not running."""
+
+    error_key = "addon_not_running_error"
+    message_template = "Add-on {addon} is not running"
+
+    def __init__(
+        self, logger: Callable[..., None] | None = None, *, addon: str
+    ) -> None:
+        """Initialize exception."""
+        self.extra_fields = {"addon": addon}
+        super().__init__(None, logger)
+
+
 class AddonNotSupportedError(HassioNotSupportedError):
     """Addon doesn't support a function."""
 
@@ -268,11 +411,8 @@ class AddonNotSupportedArchitectureError(AddonNotSupportedError):
         architectures: list[str],
     ) -> None:
         """Initialize exception."""
-        super().__init__(
+        self.extra_fields = {"slug": slug, "architectures": ", ".join(architectures)}
-            None,
+        super().__init__(None, logger)
-            logger,
-            extra_fields={"slug": slug, "architectures": ", ".join(architectures)},
-        )
 
 
 class AddonNotSupportedMachineTypeError(AddonNotSupportedError):
@@ -289,11 +429,8 @@ class AddonNotSupportedMachineTypeError(AddonNotSupportedError):
         machine_types: list[str],
     ) -> None:
         """Initialize exception."""
-        super().__init__(
+        self.extra_fields = {"slug": slug, "machine_types": ", ".join(machine_types)}
-            None,
+        super().__init__(None, logger)
-            logger,
-            extra_fields={"slug": slug, "machine_types": ", ".join(machine_types)},
-        )
 
 
 class AddonNotSupportedHomeAssistantVersionError(AddonNotSupportedError):
@@ -310,12 +447,97 @@ class AddonNotSupportedHomeAssistantVersionError(AddonNotSupportedError):
         version: str,
     ) -> None:
         """Initialize exception."""
-        super().__init__(
+        self.extra_fields = {"slug": slug, "version": version}
-            None,
+        super().__init__(None, logger)
-            logger,
+
-            extra_fields={"slug": slug, "version": version},
+
+class AddonNotSupportedWriteStdinError(AddonNotSupportedError, APIError):
+    """Addon does not support writing to stdin."""
+
+    error_key = "addon_not_supported_write_stdin_error"
+    message_template = "Add-on {addon} does not support writing to stdin"
+
+    def __init__(
+        self, logger: Callable[..., None] | None = None, *, addon: str
+    ) -> None:
+        """Initialize exception."""
+        self.extra_fields = {"addon": addon}
+        super().__init__(None, logger)
+
+
+class AddonBuildDockerfileMissingError(AddonNotSupportedError, APIError):
+    """Raise when addon build invalid because dockerfile is missing."""
+
+    error_key = "addon_build_dockerfile_missing_error"
+    message_template = (
+        "Cannot build addon '{addon}' because dockerfile is missing. A repair "
+        "using '{repair_command}' will fix this if the cause is data "
+        "corruption. Otherwise please report this to the addon developer."
     )
 
+    def __init__(
+        self, logger: Callable[..., None] | None = None, *, addon: str
+    ) -> None:
+        """Initialize exception."""
+        self.extra_fields = {"addon": addon, "repair_command": "ha supervisor repair"}
+        super().__init__(None, logger)
+
+
+class AddonBuildArchitectureNotSupportedError(AddonNotSupportedError, APIError):
+    """Raise when addon cannot be built on system because it doesn't support its architecture."""
+
+    error_key = "addon_build_architecture_not_supported_error"
+    message_template = (
+        "Cannot build addon '{addon}' because its supported architectures "
+        "({addon_arches}) do not match the system supported architectures ({system_arches})"
+    )
+
+    def __init__(
+        self,
+        logger: Callable[..., None] | None = None,
+        *,
+        addon: str,
+        addon_arch_list: list[str],
+        system_arch_list: list[str],
+    ) -> None:
+        """Initialize exception."""
+        self.extra_fields = {
+            "addon": addon,
+            "addon_arches": ", ".join(addon_arch_list),
+            "system_arches": ", ".join(system_arch_list),
+        }
+        super().__init__(None, logger)
+
+
+class AddonUnknownError(AddonsError, APIUnknownSupervisorError):
+    """Raise when unknown error occurs taking an action for an addon."""
+
+    error_key = "addon_unknown_error"
+    message_template = "An unknown error occurred with addon {addon}"
+
+    def __init__(
+        self, logger: Callable[..., None] | None = None, *, addon: str
+    ) -> None:
+        """Initialize exception."""
+        self.extra_fields = {"addon": addon}
+        super().__init__(logger)
+
+
+class AddonBuildFailedUnknownError(AddonsError, APIUnknownSupervisorError):
+    """Raise when the build failed for an addon due to an unknown error."""
+
+    error_key = "addon_build_failed_unknown_error"
+    message_template = (
+        "An unknown error occurred while trying to build the image for addon {addon}"
+    )
+
+    def __init__(
+        self, logger: Callable[..., None] | None = None, *, addon: str
+    ) -> None:
+        """Initialize exception."""
+        self.extra_fields = {"addon": addon}
+        super().__init__(logger)
+
 
 class AddonsJobError(AddonsError, JobException):
     """Raise on job errors."""
@@ -346,13 +568,68 @@ class AuthError(HassioError):
     """Auth errors."""
 
 
-class AuthPasswordResetError(HassioError):
+# This one uses the check logs rider even though its not a 500 error because it
+# is bad practice to return error specifics from a password reset API.
+class AuthPasswordResetError(AuthError, APIError):
     """Auth error if password reset failed."""
 
+    error_key = "auth_password_reset_error"
+    message_template = (
+        f"Unable to reset password for '{{user}}'. {MESSAGE_CHECK_SUPERVISOR_LOGS}"
+    )
 
-class AuthListUsersError(HassioError):
+    def __init__(
+        self,
+        logger: Callable[..., None] | None = None,
+        *,
+        user: str,
+    ) -> None:
+        """Initialize exception."""
+        self.extra_fields = {"user": user} | EXTRA_FIELDS_LOGS_COMMAND
+        super().__init__(None, logger)
+
+
+class AuthListUsersError(AuthError, APIUnknownSupervisorError):
     """Auth error if listing users failed."""
 
+    error_key = "auth_list_users_error"
+    message_template = "Can't request listing users on Home Assistant"
+
+
+class AuthListUsersNoneResponseError(AuthError, APIInternalServerError):
+    """Auth error if listing users returned invalid None response."""
+
+    error_key = "auth_list_users_none_response_error"
+    message_template = "Home Assistant returned invalid response of `{none}` instead of a list of users. Check Home Assistant logs for details (check with `{logs_command}`)"
+    extra_fields = {"none": "None", "logs_command": "ha core logs"}
+
+    def __init__(self, logger: Callable[..., None] | None = None) -> None:
+        """Initialize exception."""
+        super().__init__(None, logger)
+
+
+class AuthInvalidNonStringValueError(AuthError, APIUnauthorized):
+    """Auth error if something besides a string provided as username or password."""
+
+    error_key = "auth_invalid_non_string_value_error"
+    message_template = "Username and password must be strings"
+
+    def __init__(
+        self,
+        logger: Callable[..., None] | None = None,
+        *,
+        headers: Mapping[str, str] | None = None,
+    ) -> None:
+        """Initialize exception."""
+        super().__init__(None, logger, headers=headers)
+
+
+class AuthHomeAssistantAPIValidationError(AuthError, APIUnknownSupervisorError):
+    """Error encountered trying to validate auth details via Home Assistant API."""
+
+    error_key = "auth_home_assistant_api_validation_error"
+    message_template = "Unable to validate authentication details with Home Assistant"
+
 
 # Host
 
@@ -385,60 +662,6 @@ class HostLogError(HostError):
     """Internal error with host log."""
 
 
-# API
-
-
-class APIError(HassioError, RuntimeError):
-    """API errors."""
-
-    status = 400
-
-    def __init__(
-        self,
-        message: str | None = None,
-        logger: Callable[..., None] | None = None,
-        *,
-        job_id: str | None = None,
-        error: HassioError | None = None,
-    ) -> None:
-        """Raise & log, optionally with job."""
-        # Allow these to be set from another error here since APIErrors essentially wrap others to add a status
-        self.error_key = error.error_key if error else None
-        self.message_template = error.message_template if error else None
-        super().__init__(
-            message, logger, extra_fields=error.extra_fields if error else None
-        )
-        self.job_id = job_id
-
-
-class APIForbidden(APIError):
-    """API forbidden error."""
-
-    status = 403
-
-
-class APINotFound(APIError):
-    """API not found error."""
-
-    status = 404
-
-
-class APIGone(APIError):
-    """API is no longer available."""
-
-    status = 410
-
-
-class APIAddonNotInstalled(APIError):
-    """Not installed addon requested at addons API."""
-
-
-class APIDBMigrationInProgress(APIError):
-    """Service is unavailable due to an offline DB migration is in progress."""
-
-    status = 503
-
-
 # Service / Discovery
 
 
@@ -616,6 +839,10 @@ class DockerError(HassioError):
     """Docker API/Transport errors."""
 
 
+class DockerBuildError(DockerError):
+    """Docker error during build."""
+
+
 class DockerAPIError(DockerError):
     """Docker API error."""
 
@@ -647,7 +874,7 @@ class DockerNoSpaceOnDevice(DockerError):
         super().__init__(None, logger=logger)
 
 
-class DockerHubRateLimitExceeded(DockerError):
+class DockerHubRateLimitExceeded(DockerError, APITooManyRequests):
     """Raise for docker hub rate limit exceeded error."""
 
     error_key = "dockerhub_rate_limit_exceeded"
@@ -655,16 +882,13 @@ class DockerHubRateLimitExceeded(DockerError):
         "Your IP address has made too many requests to Docker Hub which activated a rate limit. "
         "For more details see {dockerhub_rate_limit_url}"
     )
+    extra_fields = {
+        "dockerhub_rate_limit_url": "https://www.home-assistant.io/more-info/dockerhub-rate-limit"
+    }
 
     def __init__(self, logger: Callable[..., None] | None = None) -> None:
         """Raise & log."""
-        super().__init__(
+        super().__init__(None, logger=logger)
-            None,
-            logger=logger,
-            extra_fields={
-                "dockerhub_rate_limit_url": "https://www.home-assistant.io/more-info/dockerhub-rate-limit"
-            },
-        )
 
 
 class DockerJobError(DockerError, JobException):
@@ -735,6 +959,20 @@ class StoreNotFound(StoreError):
     """Raise if slug is not known."""
 
 
+class StoreAddonNotFoundError(StoreError, APINotFound):
+    """Raise if a requested addon is not in the store."""
+
+    error_key = "store_addon_not_found_error"
+    message_template = "Addon {addon} does not exist in the store"
+
+    def __init__(
+        self, logger: Callable[..., None] | None = None, *, addon: str
+    ) -> None:
+        """Initialize exception."""
+        self.extra_fields = {"addon": addon}
+        super().__init__(None, logger)
+
+
 class StoreJobError(StoreError, JobException):
     """Raise on job error with git."""
 
@@ -770,7 +1008,7 @@ class BackupJobError(BackupError, JobException):
     """Raise on Backup job error."""
 
 
-class BackupFileNotFoundError(BackupError):
+class BackupFileNotFoundError(BackupError, APINotFound):
     """Raise if the backup file hasn't been found."""
 
 
@@ -782,6 +1020,55 @@ class BackupFileExistError(BackupError):
     """Raise if the backup file already exists."""
 
 
+class AddonBackupMetadataInvalidError(BackupError, APIError):
+    """Raise if invalid metadata file provided for addon in backup."""
+
+    error_key = "addon_backup_metadata_invalid_error"
+    message_template = (
+        "Metadata file for add-on {addon} in backup is invalid: {validation_error}"
+    )
+
+    def __init__(
+        self,
+        logger: Callable[..., None] | None = None,
+        *,
+        addon: str,
+        validation_error: str,
+    ) -> None:
+        """Initialize exception."""
+        self.extra_fields = {"addon": addon, "validation_error": validation_error}
+        super().__init__(None, logger)
+
+
+class AddonPrePostBackupCommandReturnedError(BackupError, APIError):
+    """Raise when addon's pre/post backup command returns an error."""
+
+    error_key = "addon_pre_post_backup_command_returned_error"
+    message_template = (
+        "Pre-/Post backup command for add-on {addon} returned error code: "
+        "{exit_code}. Please report this to the addon developer. Enable debug "
+        "logging to capture complete command output using {debug_logging_command}"
+    )
+
+    def __init__(
+        self, logger: Callable[..., None] | None = None, *, addon: str, exit_code: int
+    ) -> None:
+        """Initialize exception."""
+        self.extra_fields = {
+            "addon": addon,
+            "exit_code": exit_code,
+            "debug_logging_command": "ha supervisor options --logging debug",
+        }
+        super().__init__(None, logger)
+
+
+class BackupRestoreUnknownError(BackupError, APIUnknownSupervisorError):
+    """Raise when an unknown error occurs during backup or restore."""
+
+    error_key = "backup_restore_unknown_error"
+    message_template = "An unknown error occurred during backup/restore"
+
+
 # Security
 
 

supervisor/jobs/__init__.py

@@ -102,13 +102,17 @@ class SupervisorJobError:
         "Unknown error, see Supervisor logs (check with 'ha supervisor logs')"
     )
     stage: str | None = None
+    error_key: str | None = None
+    extra_fields: dict[str, Any] | None = None
 
-    def as_dict(self) -> dict[str, str | None]:
+    def as_dict(self) -> dict[str, Any]:
         """Return dictionary representation."""
         return {
             "type": self.type_.__name__,
             "message": self.message,
             "stage": self.stage,
+            "error_key": self.error_key,
+            "extra_fields": self.extra_fields,
         }
 
 
@@ -158,7 +162,9 @@ class SupervisorJob:
     def capture_error(self, err: HassioError | None = None) -> None:
         """Capture an error or record that an unknown error has occurred."""
         if err:
-            new_error = SupervisorJobError(type(err), str(err), self.stage)
+            new_error = SupervisorJobError(
+                type(err), str(err), self.stage, err.error_key, err.extra_fields
+            )
         else:
             new_error = SupervisorJobError(stage=self.stage)
         self.errors += [new_error]

supervisor/supervisor.py

@@ -28,8 +28,8 @@ from .exceptions import (
     DockerError,
     HostAppArmorError,
     SupervisorAppArmorError,
-    SupervisorError,
     SupervisorJobError,
+    SupervisorUnknownError,
     SupervisorUpdateError,
 )
 from .jobs.const import JobCondition, JobThrottle
@@ -261,7 +261,7 @@ class Supervisor(CoreSysAttributes):
         try:
             return await self.instance.stats()
         except DockerError as err:
-            raise SupervisorError() from err
+            raise SupervisorUnknownError() from err
 
     async def repair(self):
         """Repair local Supervisor data."""

tests/addons/test_addon.py

@@ -5,6 +5,7 @@ from datetime import timedelta
 import errno
 from http import HTTPStatus
 from pathlib import Path
+from typing import Any
 from unittest.mock import MagicMock, PropertyMock, call, patch
 
 import aiodocker
@@ -23,7 +24,13 @@ from supervisor.docker.addon import DockerAddon
 from supervisor.docker.const import ContainerState
 from supervisor.docker.manager import CommandReturn, DockerAPI
 from supervisor.docker.monitor import DockerContainerStateEvent
-from supervisor.exceptions import AddonsError, AddonsJobError, AudioUpdateError
+from supervisor.exceptions import (
+    AddonPrePostBackupCommandReturnedError,
+    AddonsJobError,
+    AddonUnknownError,
+    AudioUpdateError,
+    HassioError,
+)
 from supervisor.hardware.helper import HwHelper
 from supervisor.ingress import Ingress
 from supervisor.store.repository import Repository
@@ -502,31 +509,26 @@ async def test_backup_with_pre_post_command(
 
 
 @pytest.mark.parametrize(
-    "get_error,exception_on_exec",
+    ("container_get_side_effect", "exec_run_side_effect", "exc_type_raised"),
     [
-        (NotFound("missing"), False),
+        (NotFound("missing"), [(1, None)], AddonUnknownError),
-        (DockerException(), False),
+        (DockerException(), [(1, None)], AddonUnknownError),
-        (None, True),
+        (None, DockerException(), AddonUnknownError),
-        (None, False),
+        (None, [(1, None)], AddonPrePostBackupCommandReturnedError),
     ],
 )
+@pytest.mark.usefixtures("tmp_supervisor_data", "path_extern")
 async def test_backup_with_pre_command_error(
     coresys: CoreSys,
     install_addon_ssh: Addon,
     container: MagicMock,
-    get_error: DockerException | None,
+    container_get_side_effect: DockerException | None,
-    exception_on_exec: bool,
+    exec_run_side_effect: DockerException | list[tuple[int, Any]],
-    tmp_supervisor_data,
+    exc_type_raised: type[HassioError],
-    path_extern,
 ) -> None:
     """Test backing up an addon with error running pre command."""
-    if get_error:
+    coresys.docker.containers.get.side_effect = container_get_side_effect
-        coresys.docker.containers.get.side_effect = get_error
+    container.exec_run.side_effect = exec_run_side_effect
-
-    if exception_on_exec:
-        container.exec_run.side_effect = DockerException()
-    else:
-        container.exec_run.return_value = (1, None)
 
     install_addon_ssh.path_data.mkdir()
     await install_addon_ssh.load()
@@ -535,7 +537,7 @@ async def test_backup_with_pre_command_error(
     with (
         patch.object(DockerAddon, "is_running", return_value=True),
         patch.object(Addon, "backup_pre", new=PropertyMock(return_value="backup_pre")),
-        pytest.raises(AddonsError),
+        pytest.raises(exc_type_raised),
     ):
         assert await install_addon_ssh.backup(tarfile) is None
 
@@ -947,7 +949,7 @@ async def test_addon_load_succeeds_with_docker_errors(
     )
     caplog.clear()
     await install_addon_ssh.load()
-    assert "Invalid build environment" in caplog.text
+    assert "Cannot build addon 'local_ssh' because dockerfile is missing" in caplog.text
 
     # Image build failure
     caplog.clear()

tests/addons/test_build.py

@@ -3,10 +3,12 @@
 from unittest.mock import PropertyMock, patch
 
 from awesomeversion import AwesomeVersion
+import pytest
 
 from supervisor.addons.addon import Addon
 from supervisor.addons.build import AddonBuild
 from supervisor.coresys import CoreSys
+from supervisor.exceptions import AddonBuildDockerfileMissingError
 
 from tests.common import is_in_list
 
@@ -102,11 +104,11 @@ async def test_build_valid(coresys: CoreSys, install_addon_ssh: Addon):
             type(coresys.arch), "default", new=PropertyMock(return_value="aarch64")
         ),
     ):
-        assert await build.is_valid()
+        assert (await build.is_valid()) is None
 
 
 async def test_build_invalid(coresys: CoreSys, install_addon_ssh: Addon):
-    """Test platform set in docker args."""
+    """Test build not supported because Dockerfile missing for specified architecture."""
     build = await AddonBuild(coresys, install_addon_ssh).load_config()
     with (
         patch.object(
@@ -115,5 +117,6 @@ async def test_build_invalid(coresys: CoreSys, install_addon_ssh: Addon):
         patch.object(
             type(coresys.arch), "default", new=PropertyMock(return_value="amd64")
         ),
+        pytest.raises(AddonBuildDockerfileMissingError),
     ):
-        assert not await build.is_valid()
+        await build.is_valid()

tests/api/test_addons.py

@@ -5,6 +5,7 @@ from unittest.mock import MagicMock, PropertyMock, patch
 
 from aiohttp import ClientResponse
 from aiohttp.test_utils import TestClient
+from docker.errors import DockerException
 import pytest
 
 from supervisor.addons.addon import Addon
@@ -471,6 +472,11 @@ async def test_addon_options_boot_mode_manual_only_invalid(
         body["message"]
         == "Addon local_example boot option is set to manual_only so it cannot be changed"
     )
+    assert body["error_key"] == "addon_boot_config_cannot_change_error"
+    assert body["extra_fields"] == {
+        "addon": "local_example",
+        "boot_config": "manual_only",
+    }
 
 
 async def get_message(resp: ClientResponse, json_expected: bool) -> str:
@@ -539,3 +545,131 @@ async def test_addon_not_installed(
     resp = await api_client.request(method, url)
     assert resp.status == 400
     assert await get_message(resp, json_expected) == "Addon is not installed"
+
+
+async def test_addon_set_options(api_client: TestClient, install_addon_example: Addon):
+    """Test setting options for an addon."""
+    resp = await api_client.post(
+        "/addons/local_example/options", json={"options": {"message": "test"}}
+    )
+    assert resp.status == 200
+    assert install_addon_example.options == {"message": "test"}
+
+
+async def test_addon_set_options_error(
+    api_client: TestClient, install_addon_example: Addon
+):
+    """Test setting options for an addon."""
+    resp = await api_client.post(
+        "/addons/local_example/options", json={"options": {"message": True}}
+    )
+    assert resp.status == 400
+    body = await resp.json()
+    assert (
+        body["message"]
+        == "Add-on local_example has invalid options: not a valid value. Got {'message': True}"
+    )
+    assert body["error_key"] == "addon_configuration_invalid_error"
+    assert body["extra_fields"] == {
+        "addon": "local_example",
+        "validation_error": "not a valid value. Got {'message': True}",
+    }
+
+
+async def test_addon_start_options_error(
+    api_client: TestClient,
+    install_addon_example: Addon,
+    caplog: pytest.LogCaptureFixture,
+):
+    """Test error writing options when trying to start addon."""
+    install_addon_example.options = {"message": "hello"}
+
+    # Simulate OS error trying to write the file
+    with patch("supervisor.utils.json.atomic_write", side_effect=OSError("fail")):
+        resp = await api_client.post("/addons/local_example/start")
+        assert resp.status == 500
+        body = await resp.json()
+        assert (
+            body["message"]
+            == "An unknown error occurred with addon local_example. Check supervisor logs for details (check with 'ha supervisor logs')"
+        )
+        assert body["error_key"] == "addon_unknown_error"
+        assert body["extra_fields"] == {
+            "addon": "local_example",
+            "logs_command": "ha supervisor logs",
+        }
+        assert "Add-on local_example can't write options" in caplog.text
+
+    # Simulate an update with a breaking change for options schema creating failure on start
+    caplog.clear()
+    install_addon_example.data["schema"] = {"message": "bool"}
+    resp = await api_client.post("/addons/local_example/start")
+    assert resp.status == 400
+    body = await resp.json()
+    assert (
+        body["message"]
+        == "Add-on local_example has invalid options: expected boolean. Got {'message': 'hello'}"
+    )
+    assert body["error_key"] == "addon_configuration_invalid_error"
+    assert body["extra_fields"] == {
+        "addon": "local_example",
+        "validation_error": "expected boolean. Got {'message': 'hello'}",
+    }
+    assert (
+        "Add-on local_example has invalid options: expected boolean. Got {'message': 'hello'}"
+        in caplog.text
+    )
+
+
+@pytest.mark.parametrize(("method", "action"), [("get", "stats"), ("post", "stdin")])
+@pytest.mark.usefixtures("install_addon_example")
+async def test_addon_not_running_error(
+    api_client: TestClient, method: str, action: str
+):
+    """Test addon not running error for endpoints that require that."""
+    with patch.object(
+        Addon, "with_stdin", return_value=PropertyMock(return_value=True)
+    ):
+        resp = await api_client.request(method, f"/addons/local_example/{action}")
+
+    assert resp.status == 400
+    body = await resp.json()
+    assert body["message"] == "Add-on local_example is not running"
+    assert body["error_key"] == "addon_not_running_error"
+    assert body["extra_fields"] == {"addon": "local_example"}
+
+
+@pytest.mark.usefixtures("install_addon_example")
+async def test_addon_write_stdin_not_supported_error(api_client: TestClient):
+    """Test error when trying to write stdin to addon that does not support it."""
+    resp = await api_client.post("/addons/local_example/stdin")
+    assert resp.status == 400
+    body = await resp.json()
+    assert body["message"] == "Add-on local_example does not support writing to stdin"
+    assert body["error_key"] == "addon_not_supported_write_stdin_error"
+    assert body["extra_fields"] == {"addon": "local_example"}
+
+
+@pytest.mark.usefixtures("install_addon_ssh")
+async def test_addon_rebuild_fails_error(api_client: TestClient, coresys: CoreSys):
+    """Test error when build fails during rebuild for addon."""
+    coresys.hardware.disk.get_disk_free_space = lambda x: 5000
+    coresys.docker.containers.run.side_effect = DockerException("fail")
+
+    with (
+        patch.object(CpuArch, "supported", new=PropertyMock(return_value=["aarch64"])),
+        patch.object(CpuArch, "default", new=PropertyMock(return_value="aarch64")),
+        patch.object(AddonBuild, "get_docker_args", return_value={}),
+    ):
+        resp = await api_client.post("/addons/local_ssh/rebuild")
+    assert resp.status == 500
+    body = await resp.json()
+    assert (
+        body["message"]
+        == "An unknown error occurred while trying to build the image for addon local_ssh. Check supervisor logs for details (check with 'ha supervisor logs')"
+    )
+    assert body["error_key"] == "addon_build_failed_unknown_error"
+    assert body["extra_fields"] == {
+        "addon": "local_ssh",
+        "logs_command": "ha supervisor logs",
+    }

tests/api/test_auth.py

@@ -6,9 +6,12 @@ from unittest.mock import AsyncMock, MagicMock, patch
 from aiohttp.hdrs import WWW_AUTHENTICATE
 from aiohttp.test_utils import TestClient
 import pytest
+from securetar import Any
 
 from supervisor.addons.addon import Addon
 from supervisor.coresys import CoreSys
+from supervisor.exceptions import HomeAssistantAPIError, HomeAssistantWSError
+from supervisor.homeassistant.api import HomeAssistantAPI
 
 from tests.common import MockResponse
 from tests.const import TEST_ADDON_SLUG
@@ -100,6 +103,52 @@ async def test_password_reset(
     assert "Successful password reset for 'john'" in caplog.text
 
 
+@pytest.mark.parametrize(
+    ("post_mock", "expected_log"),
+    [
+        (
+            MagicMock(return_value=MockResponse(status=400)),
+            "The user 'john' is not registered",
+        ),
+        (
+            MagicMock(side_effect=HomeAssistantAPIError("fail")),
+            "Can't request password reset on Home Assistant: fail",
+        ),
+    ],
+)
+async def test_failed_password_reset(
+    api_client: TestClient,
+    coresys: CoreSys,
+    caplog: pytest.LogCaptureFixture,
+    websession: MagicMock,
+    post_mock: MagicMock,
+    expected_log: str,
+):
+    """Test failed password reset."""
+    coresys.homeassistant.api.access_token = "abc123"
+    # pylint: disable-next=protected-access
+    coresys.homeassistant.api._access_token_expires = datetime.now(tz=UTC) + timedelta(
+        days=1
+    )
+
+    websession.post = post_mock
+    resp = await api_client.post(
+        "/auth/reset", json={"username": "john", "password": "doe"}
+    )
+    assert resp.status == 400
+    body = await resp.json()
+    assert (
+        body["message"]
+        == "Unable to reset password for 'john'. Check supervisor logs for details (check with 'ha supervisor logs')"
+    )
+    assert body["error_key"] == "auth_password_reset_error"
+    assert body["extra_fields"] == {
+        "user": "john",
+        "logs_command": "ha supervisor logs",
+    }
+    assert expected_log in caplog.text
+
+
 async def test_list_users(
     api_client: TestClient, coresys: CoreSys, ha_ws_client: AsyncMock
 ):
@@ -120,6 +169,48 @@ async def test_list_users(
     ]
 
 
+@pytest.mark.parametrize(
+    ("send_command_mock", "error_response", "expected_log"),
+    [
+        (
+            AsyncMock(return_value=None),
+            {
+                "result": "error",
+                "message": "Home Assistant returned invalid response of `None` instead of a list of users. Check Home Assistant logs for details (check with `ha core logs`)",
+                "error_key": "auth_list_users_none_response_error",
+                "extra_fields": {"none": "None", "logs_command": "ha core logs"},
+            },
+            "Home Assistant returned invalid response of `None` instead of a list of users. Check Home Assistant logs for details (check with `ha core logs`)",
+        ),
+        (
+            AsyncMock(side_effect=HomeAssistantWSError("fail")),
+            {
+                "result": "error",
+                "message": "Can't request listing users on Home Assistant. Check supervisor logs for details (check with 'ha supervisor logs')",
+                "error_key": "auth_list_users_error",
+                "extra_fields": {"logs_command": "ha supervisor logs"},
+            },
+            "Can't request listing users on Home Assistant: fail",
+        ),
+    ],
+)
+async def test_list_users_failure(
+    api_client: TestClient,
+    ha_ws_client: AsyncMock,
+    caplog: pytest.LogCaptureFixture,
+    send_command_mock: AsyncMock,
+    error_response: dict[str, Any],
+    expected_log: str,
+):
+    """Test failure listing users via API."""
+    ha_ws_client.async_send_command = send_command_mock
+    resp = await api_client.get("/auth/list")
+    assert resp.status == 500
+    result = await resp.json()
+    assert result == error_response
+    assert expected_log in caplog.text
+
+
 @pytest.mark.parametrize(
     ("field", "api_client"),
     [("username", TEST_ADDON_SLUG), ("user", TEST_ADDON_SLUG)],
@@ -156,6 +247,13 @@ async def test_auth_json_failure_none(
     mock_check_login.return_value = True
     resp = await api_client.post("/auth", json={"username": user, "password": password})
     assert resp.status == 401
+    assert (
+        resp.headers["WWW-Authenticate"]
+        == 'Basic realm="Home Assistant Authentication"'
+    )
+    body = await resp.json()
+    assert body["message"] == "Username and password must be strings"
+    assert body["error_key"] == "auth_invalid_non_string_value_error"
 
 
 @pytest.mark.parametrize("api_client", [TEST_ADDON_SLUG], indirect=True)
@@ -267,3 +365,26 @@ async def test_non_addon_token_no_auth_access(api_client: TestClient):
     """Test auth where add-on is not allowed to access auth API."""
     resp = await api_client.post("/auth", json={"username": "test", "password": "pass"})
     assert resp.status == 403
+
+
+@pytest.mark.parametrize("api_client", [TEST_ADDON_SLUG], indirect=True)
+@pytest.mark.usefixtures("install_addon_ssh")
+async def test_auth_backend_login_failure(api_client: TestClient):
+    """Test backend login failure on auth."""
+    with (
+        patch.object(HomeAssistantAPI, "check_api_state", return_value=True),
+        patch.object(
+            HomeAssistantAPI, "make_request", side_effect=HomeAssistantAPIError("fail")
+        ),
+    ):
+        resp = await api_client.post(
+            "/auth", json={"username": "test", "password": "pass"}
+        )
+    assert resp.status == 500
+    body = await resp.json()
+    assert (
+        body["message"]
+        == "Unable to validate authentication details with Home Assistant. Check supervisor logs for details (check with 'ha supervisor logs')"
+    )
+    assert body["error_key"] == "auth_home_assistant_api_validation_error"
+    assert body["extra_fields"] == {"logs_command": "ha supervisor logs"}

tests/api/test_backups.py

@@ -17,6 +17,7 @@ from supervisor.const import CoreState
 from supervisor.coresys import CoreSys
 from supervisor.docker.manager import DockerAPI
 from supervisor.exceptions import (
+    AddonPrePostBackupCommandReturnedError,
     AddonsError,
     BackupInvalidError,
     HomeAssistantBackupError,
@@ -24,6 +25,7 @@ from supervisor.exceptions import (
 from supervisor.homeassistant.core import HomeAssistantCore
 from supervisor.homeassistant.module import HomeAssistant
 from supervisor.homeassistant.websocket import HomeAssistantWebSocket
+from supervisor.jobs import SupervisorJob
 from supervisor.mounts.mount import Mount
 from supervisor.supervisor import Supervisor
 
@@ -401,6 +403,8 @@ async def test_api_backup_errors(
             "type": "BackupError",
             "message": str(err),
             "stage": None,
+            "error_key": None,
+            "extra_fields": None,
         }
     ]
     assert job["child_jobs"][2]["name"] == "backup_store_folders"
@@ -437,6 +441,8 @@ async def test_api_backup_errors(
             "type": "HomeAssistantBackupError",
             "message": "Backup error",
             "stage": "home_assistant",
+            "error_key": None,
+            "extra_fields": None,
         }
     ]
     assert job["child_jobs"][0]["name"] == "backup_store_homeassistant"
@@ -445,6 +451,8 @@ async def test_api_backup_errors(
             "type": "HomeAssistantBackupError",
             "message": "Backup error",
             "stage": None,
+            "error_key": None,
+            "extra_fields": None,
         }
     ]
     assert len(job["child_jobs"]) == 1
@@ -749,6 +757,8 @@ async def test_backup_to_multiple_locations_error_on_copy(
             "type": "BackupError",
             "message": "Could not copy backup to .cloud_backup due to: ",
             "stage": None,
+            "error_key": None,
+            "extra_fields": None,
         }
     ]
 
@@ -1483,3 +1493,44 @@ async def test_immediate_list_after_missing_file_restore(
     result = await resp.json()
     assert len(result["data"]["backups"]) == 1
     assert result["data"]["backups"][0]["slug"] == "93b462f8"
+
+
+@pytest.mark.parametrize("command", ["backup_pre", "backup_post"])
+@pytest.mark.usefixtures("install_addon_example", "tmp_supervisor_data")
+async def test_pre_post_backup_command_error(
+    api_client: TestClient, coresys: CoreSys, container: MagicMock, command: str
+):
+    """Test pre/post backup command error."""
+    await coresys.core.set_state(CoreState.RUNNING)
+    coresys.hardware.disk.get_disk_free_space = lambda x: 5000
+
+    container.status = "running"
+    container.exec_run.return_value = (1, b"")
+    with patch.object(Addon, command, return_value=PropertyMock(return_value="test")):
+        resp = await api_client.post(
+            "/backups/new/partial", json={"addons": ["local_example"]}
+        )
+
+    assert resp.status == 200
+    body = await resp.json()
+    job_id = body["data"]["job_id"]
+    job: SupervisorJob | None = None
+    for j in coresys.jobs.jobs:
+        if j.name == "backup_store_addons" and j.parent_id == job_id:
+            job = j
+            break
+
+    assert job
+    assert job.done is True
+    assert job.errors[0].type_ == AddonPrePostBackupCommandReturnedError
+    assert job.errors[0].message == (
+        "Pre-/Post backup command for add-on local_example returned error code: "
+        "1. Please report this to the addon developer. Enable debug "
+        "logging to capture complete command output using ha supervisor options --logging debug"
+    )
+    assert job.errors[0].error_key == "addon_pre_post_backup_command_returned_error"
+    assert job.errors[0].extra_fields == {
+        "addon": "local_example",
+        "exit_code": 1,
+        "debug_logging_command": "ha supervisor options --logging debug",
+    }

tests/api/test_jobs.py

@@ -374,6 +374,8 @@ async def test_job_with_error(
                     "type": "SupervisorError",
                     "message": "bad",
                     "stage": "test",
+                    "error_key": None,
+                    "extra_fields": None,
                 }
             ],
             "child_jobs": [
@@ -391,6 +393,8 @@ async def test_job_with_error(
                             "type": "SupervisorError",
                             "message": "bad",
                             "stage": None,
+                            "error_key": None,
+                            "extra_fields": None,
                         }
                     ],
                     "child_jobs": [],

tests/api/test_store.py

@@ -4,7 +4,6 @@ import asyncio
 from pathlib import Path
 from unittest.mock import AsyncMock, MagicMock, PropertyMock, patch
 
-from aiohttp import ClientResponse
 from aiohttp.test_utils import TestClient
 from awesomeversion import AwesomeVersion
 import pytest
@@ -290,14 +289,6 @@ async def test_api_detached_addon_documentation(
     assert result == "Addon local_ssh does not exist in the store"
 
 
-async def get_message(resp: ClientResponse, json_expected: bool) -> str:
-    """Get message from response based on response type."""
-    if json_expected:
-        body = await resp.json()
-        return body["message"]
-    return await resp.text()
-
-
 @pytest.mark.parametrize(
     ("method", "url", "json_expected"),
     [
@@ -323,7 +314,13 @@ async def test_store_addon_not_found(
     """Test store addon not found error."""
     resp = await api_client.request(method, url)
     assert resp.status == 404
-    assert await get_message(resp, json_expected) == "Addon bad does not exist"
+    if json_expected:
+        body = await resp.json()
+        assert body["message"] == "Addon bad does not exist in the store"
+        assert body["error_key"] == "store_addon_not_found_error"
+        assert body["extra_fields"] == {"addon": "bad"}
+    else:
+        assert await resp.text() == "Addon bad does not exist in the store"
 
 
 @pytest.mark.parametrize(

tests/api/test_supervisor.py

@@ -7,6 +7,7 @@ from unittest.mock import AsyncMock, MagicMock, PropertyMock, patch
 from aiohttp.test_utils import TestClient
 from awesomeversion import AwesomeVersion
 from blockbuster import BlockingError
+from docker.errors import DockerException
 import pytest
 
 from supervisor.const import CoreState
@@ -407,3 +408,37 @@ async def test_api_progress_updates_supervisor_update(
             "done": True,
         },
     ]
+
+
+async def test_api_supervisor_stats(api_client: TestClient, coresys: CoreSys):
+    """Test supervisor stats."""
+    coresys.docker.containers.get.return_value.status = "running"
+    coresys.docker.containers.get.return_value.stats.return_value = load_json_fixture(
+        "container_stats.json"
+    )
+
+    resp = await api_client.get("/supervisor/stats")
+    assert resp.status == 200
+    result = await resp.json()
+    assert result["data"]["cpu_percent"] == 90.0
+    assert result["data"]["memory_usage"] == 59700000
+    assert result["data"]["memory_limit"] == 4000000000
+    assert result["data"]["memory_percent"] == 1.49
+
+
+async def test_supervisor_api_stats_failure(
+    api_client: TestClient, coresys: CoreSys, caplog: pytest.LogCaptureFixture
+):
+    """Test supervisor stats failure."""
+    coresys.docker.containers.get.side_effect = DockerException("fail")
+
+    resp = await api_client.get("/supervisor/stats")
+    assert resp.status == 500
+    body = await resp.json()
+    assert (
+        body["message"]
+        == "An unknown error occurred with Supervisor. Check supervisor logs for details (check with 'ha supervisor logs')"
+    )
+    assert body["error_key"] == "supervisor_unknown_error"
+    assert body["extra_fields"] == {"logs_command": "ha supervisor logs"}
+    assert "Could not inspect container 'hassio_supervisor': fail" in caplog.text

tests/jobs/test_job_manager.py

@@ -200,6 +200,8 @@ async def test_notify_on_change(coresys: CoreSys, ha_ws_client: AsyncMock):
                                 "type": "HassioError",
                                 "message": "Unknown error, see Supervisor logs (check with 'ha supervisor logs')",
                                 "stage": "test",
+                                "error_key": None,
+                                "extra_fields": None,
                             }
                         ],
                         "created": ANY,
@@ -228,6 +230,8 @@ async def test_notify_on_change(coresys: CoreSys, ha_ws_client: AsyncMock):
                             "type": "HassioError",
                             "message": "Unknown error, see Supervisor logs (check with 'ha supervisor logs')",
                             "stage": "test",
+                            "error_key": None,
+                            "extra_fields": None,
                         }
                     ],
                     "created": ANY,