Recovery: when something does not start

What it is

A page of ways back, in the order to try them. WolOS keeps two slots (copies of the system), asks for a recovery key if the disk cannot open, keeps a list of recent settings changes you can undo, and has checks that name what is wrong. Words in bold are defined in the Glossary.

Why

When something does not start you have the least patience and the least information. Each tool here answers one question: which slot am I on, can I open my disk, what did I change, which file differs, which device lacks a driver.

How

Find your symptom, then follow the numbered steps.

The system will not start after an update

Nothing to do. If the new slot fails to start three times in a row, the computer starts the other slot by itself.

1. Wait for the second start. The computer restarts by itself up to three times. You see the old system, with your files and apps as they were.
2. Check which slot runs. Open a terminal and run wol update status. You see which slot is running and what the last check found.
3. Try again later. The failed slot sorts last in the boot menu. An older slot cannot be started again once it is retired; this is deliberate (Secure Boot).
4. To go back on purpose: wol update rollback (asks for the administrator password) chooses the previous restore point for the next start. Settings > Restore lists the earlier system states.

The disk asks for a password

At start the computer tries the security chip (TPM), then your account password, then the recovery key. You are asked once; the password and the recovery key both answer the same prompt.

1. Type your account password. This is the usual case after a Secure Boot or firmware change: the chip refuses because the measured state changed. You see WolOS start. The next start is automatic again, because the chip is sealed again to the state measured now.
2. If you forgot the password, type the recovery key. It was shown once at the end of the install. If you chose Save to USB, it is a file on that stick.
3. If you changed your password with passwd in a terminal, the disk still wants the previous one; the chip and the recovery key still work. Change your password in Settings > Users & Groups instead, which keeps the disk password in step.
4. Accented letters cannot be typed before WolOS starts. That is why the installer asks for letters, digits and common symbols for a disk password.

With no password, no chip and no recovery key, the data cannot be read. That is what encryption means.

A setting broke the desktop

1. Open Settings > Restore. You see Recent Changes: what changed, when, and who made it (System Settings, Control Center, Terminal, a script or an assistant).
2. Click Undo on the change. From a terminal: wol history lists changes, wol undo undoes the last one.
3. If the desktop itself misbehaves, run wol shell reload. The desktop reconnects to the window manager by itself after it restarts, and the lock screen comes back if it crashes.
4. If a theme or plugin is the cause: wol theme list then wol theme set wol-dark (or any listed id) sets a theme again; wol plugin disable <id> turns a plugin off. A plugin that keeps failing is turned off on its own.

A system file or a device is wrong

1. Check the system files: wol base verify. You see every base file that differs from the signed list, or nothing. The same check runs at every start.
2. Check devices: wol hw status. You see devices that need a driver or firmware, each with the fix. wol hw fix loads missing drivers (administrator password); wol hw fix --yes also installs packages.
3. Check sound: wol audio doctor. wol audio reset --yes forgets stored sound defaults and restarts the sound server.
4. Check games: wol games doctor prints the command that fixes each failed check.
5. Deliberate changes: on a sealed system, wol seal off makes it writable until the next update (developer mode).

A black screen after the install

• VirtualBox: check the virtual machine's display settings on Download.
• Real hardware: if you can reach a terminal, wol hw status names devices that need a driver and prints the fix.

Starting over

• Try WolOS from the stick changes nothing on the disk.
• The installer can install again over an earlier WolOS. Next to Windows, the other system is kept (Installing next to Windows).
• If an install fails, the Failed page names the step. The log stays on the installed system at /var/log/wolos-install.log. See Installing WolOS.

What to include in a report

wol about, wol update status, wol boot status (Secure Boot, TPM and seal state), and for sound the diagnostics that Copy diagnostics in Settings > Sound > Troubleshooting puts on the clipboard. Report on GitHub.

If something goes wrong