SteamOS update failure and rollback
Distinguish an update that will not download, an update that will not install, and a completed update that caused a regression. They require different evidence and recovery choices.
Do not interrupt an update that is visibly progressing. If it has failed, preserve the exact error and avoid repeatedly switching update channels or modifying the base system.
Scope
This flow addresses SteamOS image updates, not individual game, shader-cache, Flatpak, or Proton downloads. Valve release notes show that a SteamOS release can change the kernel, Mesa, desktop, Gamescope, hardware support, and many other variables together.
Classify the failure
| Stage | Evidence to record | First safe check |
|---|---|---|
Download does not start or complete | Network state, error text, free space | Stable network and storage capacity |
Installation reports failure | Percentage, code, power, channel | Restart once after preserving the error |
Update completes but boot/session regresses | Old/new build, peripherals, symptom | Minimal peripherals and supported rollback |
Device no longer boots either session | Power/display behavior and recovery USB | Official recovery decision flow |
Preflight and logs
Keep the official charger connected where practical. From Desktop Mode, collect read-only state:
Also record the update channel and build shown in Steam → Settings → System. Redact usernames, paths, network identifiers, and tokens before sharing logs.
Remove environmental variables
- Disconnect nonessential docks, external drives, displays, and USB devices.
- Use a stable network and reliable power.
- Ensure
/and/homeare not full. - Record Decky plugins, custom scripts, disabled read-only protection, and
pacmanchanges. - Restart normally once; retry only after the failed state is understood.
Do not delete unknown update files or package databases. A managed image update is not repaired by blindly applying Arch Linux desktop instructions.
Completed update regression
Compare the installed build with the relevant Valve release notes. Test the failure with minimal peripherals and third-party customizations disabled through their documented controls. Keep only one variable changed at a time.
If Valve offers a rollback path, use it for a recent regression and record the resulting version. Confirm the system is stable before allowing the same update again.
Repair and reinstall boundary
Use official Repair only when current recovery media offers it and the description matches damaged system state. Factory reset and full install/re-image are destructive. Back up accessible data before either and use Install, repair, reset, or roll back SteamOS.
Verification
After retry, rollback, or repair, verify two restarts, Gaming Mode, Desktop Mode, network, controls, sound, storage space, suspend/resume, and a representative game. Re-enable third-party changes one at a time only after the base system remains stable.
Rollback plan
Before an update on a modified system, preserve user data and document all base-system changes. If rollback restores stability, remain on the working build while checking Valve's newer notes and known issues; do not conceal the failed build when reporting the problem.
Known issues
- Valve support pages and release notes are updated independently; preserve access dates and exact builds.
- A full filesystem, unstable network, failing storage, or unsupported base-system modification can look like an update-service failure.
- Rollback availability and controls can differ by product and installed image.
Frequently asked questions
Should I keep retrying an update that fails at the same point?Should I keep retrying an update that fails at the same point?
Is rollback the same as re-imaging SteamOS?Is rollback the same as re-imaging SteamOS?
Sources
Version history
- 2026-07-15: Phase 3 reviewed update classification, rollback, and recovery boundaries.