This document lists why a Fuchsia device may reboot. Some are self-explanatory
while others require some additional context.

Outline:

- [Terminology](https://fuchsia.dev/fuchsia-src/concepts/process/why_fuchsia_devices_reboot#terminology)
- [Reboot reasons listed](https://fuchsia.dev/fuchsia-src/concepts/process/why_fuchsia_devices_reboot#reboot-reasons)
- [Where to find reboot reasons](https://fuchsia.dev/fuchsia-src/concepts/process/why_fuchsia_devices_reboot#where-to-find)

## Terminology

### Ungraceful reboot

An ungraceful reboot is a reboot that is initiated by either the kernel in
response to an error, such as a kernel panic, or performed by the hardware
without software intervention, such as a hardware watchdog timeout.

### Graceful reboot

A graceful reboot is a reboot that is initiated by a userspace process. The
process may initiate the reboot in response to an error, like when a device's
temperature is too high, but Fuchsia should have the opportunity to undergo an
orderly shutdown.

## Reboot reasons listed

### Kernel panic

If the kernel is unable to recover from an internal error, that error is
considered fatal and the system will reboot.

### The system runs out of memory

If the kernel detects that the amount of free physical memory falls below a
threshold, the system will reboot. The kernel does not kill processes to try to
reclaim memory before rebooting, meaning a single process could cause a
system-wide shortage of memory and force the device to reboot.

### Cold boot

If a device loses power for long enough between when it is shut down and it
boots back up, the system will determine this to be a cold boot.

### Brownout

A device browns out when its voltage dips below an acceptable threshold. This
should only occur when there is an issue with a device's power supply or its
power related hardware.

### Hardware watchdog timeout

Zircon sets up a hardware watchdog timer that will reboot the device if it is
not reset within a specified period of time.

### Software watchdog timeout

A software watchdog timer may reboot the device if someone sets one up.

### Brief loss of power

If a device loses power for a short period of time, like when a user unplugs a
device and rapidly plugs it back in, it may be unable to determine that the
reboot was cold and will consider the reboot a result of a brief power loss. It
is important to note that there is *not* a quantitative measure of what brief is
and is hardware dependent.

### Spontaneous reboot during shutdown

A graceful shutdown was started and the device rebooted before Zircon could halt
it, e.g. while drivers were being torn down.

### User hard reset

The user held the power button to hard reset it.

### User request

The end user of the device explicitly requested a reboot of the device.

### Developer request

The developer initiated the reboot, typically via a shell command or similar
interface, including within an automated test.

### System update

A component responsible for system updates must update a package, or multiple
packages, that cannot be updated ephemerally. These packages are canonically
know as base packages.

### Retry system update

A component responsible for system updates fails to apply an update, so the
device reboots to try again (or possibly revert the update).

### ZBI swap

If the Zircon boot image is swapped, the device reboots to apply the change.

### High temperature

A component responsible for power management detects that a device's temperature
is too high and the system cannot adequately reduce the device's temperature by
throttling the CPU or reducing the audio volume.

### Session failure

If the session manager is unable to restart a crashed session or a session
determines it has failed in an unrecoverable manner, the device reboots.

### Critical component failure

If a component marked `"on_terminate": "reboot"` crashed, the device reboots.

### Critical driver failure

If a critical driver crashed, the device reboots.

### Factory data reset

Following a data reset to the factory defaults, the device reboots.

### Root job termination

If the userspace root job is terminated, e.g., because one of its critical
processes crashes, the device reboots.

### Generic graceful

The platform can know whether the reboot was graceful, but cannot distinguish
between a software update, a user request or some higher-level component
detecting the device as overheating. All the platform knows is that the reboot
was graceful.

### Unknown

There are some scenarios in which the platform cannot determine the specific
reboot reason nor can it determine if the reboot was graceful or ungraceful.

## Where to find reboot reasons

Fuchsia exposes the reason a device last (re)booted through
[FIDL](https://cs.opensource.google/fuchsia/fuchsia/+/main:/sdk/fidl/fuchsia.feedback/last_reboot_info.fidl) and tracks it on Cobalt
and the crash server.

#### Culprits

Reboots that at are the result of an error in a specific component have crash
signatures that attribute that component as the cause of the reboot. They follow
a general pattern of combining the reboot reason and the component deemed
responsible for the reboot, a.k.a. the culprit.

| Reboot reason | **FIDL** | **Cobalt event** | **Crash signature** |
|---|---|---|---|
| Kernel panic | `KERNEL_PANIC` | `KernelPanic` | Function responsible for the crash, exactly like a userspace crash report |
| System running out of memory | `SYSTEM_OUT_OF_MEMORY` | `SystemOutOfMemory` | `fuchsia-oom` or `fuchsia-oom-$CULPRIT` |
| Cold boot | `COLD` | `Cold` | N/A\* |
| Brownout | `BROWNOUT` | `Brownout` | `fuchsia-brownout` |
| Hardware watchdog timeout | `HARDWARE_WATCHDOG_TIMEOUT` | `HardwareWatchdogTimeout` | `fuchsia-hw-watchdog-timeout` |
| Software watchdog timeout | `SOFTWARE_WATCHDOG_TIMEOUT` | `SoftwareWatchdogTimeout` | `fuchsia-sw-watchdog-timeout` |
| Brief power loss | `BRIEF POWER LOSS` | `BriefPowerLoss` | `fuchsia-brief-power-loss` |
| Spontaneous reboot during shutdown | `SPONTANEOUS_REBOOT_DURING_SHUTDOWN` | `SpontaneousRebootDuringShutdown` | `fuchsia-brief-power-loss-during-shutdown`\*\* |
| User hard reset | `USER_HARD_RESET` | `UserHardReset` | `fuchsia-hard-reset-user-requested` |
| User request | `USER_REQUEST` | `UserRequest` | N/A\* |
| Developer request | `DEVELOPER_REQUEST` | `DeveloperRequest` | N/A\* |
| System update | `SYSTEM_UPDATE` | `SystemUpdate` | N/A\* |
| Retry system update | `RETRY_SYSTEM_UPDATE` | `RetrySystemUpdate` | `fuchsia-retry-system-update` |
| ZBI swap | `ZBI_SWAP` | `ZbiSwap` | N/A\* |
| High temperature | `HIGH_TEMPERATURE` | `HighTemperature` | `fuchsia-reboot-high-temperature` |
| Session failure | `SESSION_FAILURE` | `SessionFailure` | `fuchsia-session-failure` |
| Critical component failure | `CRITICAL_COMPONENT_FAILURE` | `CriticalComponentFailure` | `fuchsia-critical-component-failure` or `fuchsia-reboot-$CULPRIT-terminated` |
| Critical driver failure | `CRITICAL_DRIVER_FAILURE` | `CriticalDriverFailure` | `fuchsia-critical-driver-failure` |
| Factory data reset | `FACTORY_DATA_RESET` | `FactoryDataReset` | N/A\* |
| Root job termination | `ROOT_JOB_TERMINATION` | `RootJobTermination` | `fuchsia-root-job-termination` or `fuchsia-reboot-$CULPRIT-terminated` |
| Generic graceful | *graceful* field set to true | `GenericGraceful` | `fuchsia-undetermined-userspace-reboot` |
| Unknown | *graceful* field not set | `Unknown` | `fuchsia-reboot-log-not-parseable` |

\* Not a crash. \\

\*\* The prefix follows how the product interprets spontaneous reboots, e.g.
`fuchsia-hard-reset-during-shutdown` on products that interpret them as hard
resets.
[](https://issues.fuchsia.dev/issues/new?component=1439230&template=1881640&description=Issue+on:+https://fuchsia.dev/docs/concepts/process/why_fuchsia_devices_reboot.md "Report a bug or suggest improvements on this page") [](https://cs.opensource.google/fuchsia/fuchsia/+/main:docs/concepts/process/why_fuchsia_devices_reboot.md "View the source code of this page") [](https://ci.android.com/edit?repo=fuchsia/fuchsia/main&file=docs/concepts/process/why_fuchsia_devices_reboot.md&cloneRepo=fuchsia/fuchsia:refs/heads/main&fullPath=fuchsia/docs/concepts/process/why_fuchsia_devices_reboot.md "Edit the source code of this page")