Document OS error "Bad message" unhealthy case (#30851)

* Document OS error "Bad message" unhealthy case

With Supervisor pull request https://github.com/home-assistant/supervisor/pull/4750
we've introduced a new unhealthy condition when the operating system
raises "Bad message" errors on file system operations. This typically
points to a corrupted file system.

According to the (opt-in) Sentry error reports we see ~580 affected
systems in the last 30 days. A disproportional amount of systems are
running HAOS on Raspberry Pi. We assume that this is releated to the
known USB UAS storage problem on Raspberry Pi. Add this hints
accordingnly.

* Apply suggestions from code review

Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com>

---------

Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com>
This commit is contained in:
Stefan Agner 2024-01-15 15:48:04 +01:00 committed by GitHub
parent 5e3ade0e7c
commit 1d15b68fb2
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -0,0 +1,17 @@
---
title: "Operating System error: Bad message"
description: "More information on what to do when OS errors mark the installation as unhealthy."
---
## The issue
The Supervisor received Operating System errors during file operation (Python OSError exceptions). The error number reported was 74, "Bad message", which is typically raised on file system corruption. File system corruption can happen due to a power outage or when the system otherwise did not get shut down properly.
## The solution
Typically, Home Assistant recovers from file system corruption. If you see this error for the first time, ignore it. In case the problem gets worse, make sure to create a full backup, download it, or store it on a different system.
If this issue reappears even after a system restart, your system configuration or hardware might be at fault. Consider a clean reinstallation of your Operating System. If you are using an external USB drive, consider replacing the USB adapter or the SSD. If you are confident that the hardware is not at fault and you are using a Raspberry Pi, it might be related to incompatibility with certain UAS drives. For more background information, read this [Raspberry Pi forum post][rpi-forum-uas]. The Home Assistant OS maintains a list of devices where UAS are disabled in order to work around the problem (check config.txt on the first partition of your installation). If the USB PID/VID of your device is missing, consider [opening an issue][haos-issue] in the Home Assistant OS project.
[rpi-forum-uas]: https://forums.raspberrypi.com/viewtopic.php?t=245931
[haos-issue]: https://github.com/home-assistant/operating-system/issues/new/choose