Start here
When something goes wrong
A black screen, a desktop that won't start, an update that misbehaves. What to do, step by step, and why your files are safe while you do it.
First: your files are safe
AOS keeps the system and your data apart. An update only ever replaces the system, and it never writes over the version you are running: the new release goes into a second slot, and the previous one stays on the disk, untouched, as its own entry in the boot menu.
Your home, your apps and your settings live on a separate partition that no update touches. Whatever the screen shows, nothing below deletes them.
AOS fixes most failures by itself
A new release starts on trial. It gets three tries to reach the desktop. If it never does, because it hangs, crashes or shows a black screen, the computer goes back to the previous release by itself, and you are back where you were before the update.
So if a restart after an update looks wrong, first just wait, or restart once or twice. That is often all it takes.
The boot menu
The boot menu is hidden, but it is always there. Hold the Space bar while the computer starts. Start holding it right after you press the power button, and keep holding until a menu appears. If it doesn’t, restart and try tapping Space repeatedly instead.
The menu shows both versions of AOS on your disk, newest first. Each has three ways to start:
| Entry | Use it when |
|---|---|
| AOS (version) | The normal start |
| AOS (safe graphics, no GPU driver) | The screen stays black, flickers or freezes. Starts without the graphics driver: slower, lower resolution, but it shows a picture |
| AOS (serial console) | Only for developers with a serial cable |
Use the arrow keys and Enter. The menu runs before the operating system, so a broken driver or a broken update can’t take it away.
Black screen at start
Work down this list. Stop when it works.
- Wait two minutes. The first start after an update can take a moment, and a release that fails falls back by itself.
- Restart with the power button: hold it for ten seconds, then press it again. Do this up to three times; a failed update gives up and goes back after three tries.
- Open the boot menu (hold Space) and choose safe graphics for the newest version. If you get a desktop, the graphics driver is the problem. Report it and keep using safe graphics until a fix arrives.
- Open the boot menu and choose the older version. That is the release you had before the update, as it was.
- Try the older version with safe graphics.
- If nothing on your disk starts, start from the AOS USB stick (see below).
The desktop crashes or won’t start
If the desktop or the login screen crashes again and again, AOS stops trying after five crashes and shows a plain recovery screen instead. It is text only, so it works even when the graphics don’t. Type a number and press Enter:
| Choice | What it does |
|---|---|
| Try again | Starts the desktop once more. Fine after a one-off glitch |
| Go back to the previous version of AOS | Switches to the release you had before, after an administrator’s password, then restarts |
| Save a report | Saves a report about what failed to the disk, and to a USB stick if one is plugged in, for a bug report |
| Send a report | Sends that report to us. Shown only where sending is set up |
| Command line | A text login, for people who know their way around |
| Restart / Power off | What they say |
If the trouble started with an update, Go back to the previous version is usually the right choice.
An app misbehaves after an update
If an app crashes right after it was updated, AOS starts its previous version by itself and tells you. You can also go back by hand: open Software, go to the app’s page and choose Use previous version.
If an app is stuck in a bad state, its page in Software has Clear cache and Delete its data. That resets only that app; nothing else is touched.
You forgot your password
At the login screen, type your recovery key instead of the password: the eight groups of letters you were shown on the first start. It opens your home, and you can set a new password in Settings → Users.
If the disk itself is encrypted, the passphrase you chose at install is its recovery key.
Start from the USB stick
The AOS USB stick is a complete, working system of its own. Keep it. If nothing on the disk starts:
- Plug in the stick and start the computer from it. The firmware’s boot menu key is often F12, F8 or Esc.
- The live desktop starts without a password and doesn’t change your disk.
- From there you can check your hardware, save a report, or reinstall. Reinstalling erases the disk, so only do it when nothing else works.
Reporting what happened
A report helps us fix it for everyone. Include:
- The AOS version (the boot menu shows it, as does Settings → About).
- What you did, what you expected and what you saw. A phone photo of the screen helps.
- A saved report, if you could make one: Settings → About → Save Report, or Save a report on the recovery screen.