Aurora OS Documentation latest

Documentation › Troubleshooting

Troubleshooting

Black screens, a desktop that doesn't start, missing sound or Wi-Fi, logs, System Health and resetting settings

System Health first

Settings → System Health checks disks (SMART), free space, updates, firmware, failed services, the battery, graphics drivers and the session's own startup, and shows a fix for each problem. Guided Diagnostics prepares a local report for installation, startup and login, app problems, or screen, sound or another device — that last one opens with the computer itself (model, processor, memory, kernel, Aurora version, which session and renderer are running) and adds the devices on the bus, the disks and the kernel's warnings. Every report begins with those few lines about the machine. Raw logs are left out unless you choose to include them, you can edit the preview, and nothing is uploaded. Names that identify only your computer — your home folder, e-mail addresses, machine and disk ids, serial numbers, anything that looks like a password or a token — are replaced before you ever see the text.

The screen stays black after the boot menu

  1. Start Try Aurora OS (safe graphics).
  2. Still black: edit the entry with E and add nomodeset to the line that starts with linux.
  3. On an installed NVIDIA system: Settings → Software Updates → Additional Drivers.

The system doesn't start: recovery mode

In the boot menu choose Advanced options for Aurora GNU/Linux, then the entry ending in (recovery mode) (the previous kernel is there too, if the newest one is the problem). It starts only the essentials and, after Press Enter for system maintenance, gives a root terminal without asking a password: fix what's needed (apt, journalctl -xb to read what failed), then systemctl default to start normally or reboot. On btrfs, Aurora OS snapshots in the same menu starts yesterday's system instead.

The desktop doesn't appear after login

  • At the login screen choose Aurora Compatibility.
  • If the Aurora session fell back to labwc, the reason is in ~/.local/state/aurora/compositor-failure.log and in System Health.
  • If the top bar or dock disappear, the shell restarts by itself within a second (up to five times a minute). Its log is $XDG_RUNTIME_DIR/aurora-shell.log.
  • To log in without the desktop: Ctrl+Alt+F2 gives a text console.

An app doesn't respond

Open Task Manager (Ctrl+Shift+Esc), select it, End Task; if it stays, Kill. From a terminal: pkill NAME or kill -9 PID.

No sound

  • Control Center → the arrow next to the volume: choose the right output device.
  • Settings → Sound → Volume Mixer: is the app muted or very low?
  • systemctl --user restart pipewire wireplumber restarts the sound system.

No Wi-Fi

  • Airplane Mode off? Wi-Fi tile on?
  • nmcli radio shows whether Wi-Fi is blocked; rfkill list shows a hardware switch.
  • Some Broadcom and Realtek cards need a newer kernel: sudo apt install -t trixie-backports linux-image-amd64.

An update broke something

Start the snapshot from before the update from the boot menu: see Snapshots and recovery.

Reset settings

gsettings reset-recursively org.aurora.desktop    # Aurora's desktop settings
rm ~/.config/labwc/rc.xml                         # keyboard shortcuts and window settings
aurora-wayfire-config                             # regenerate the Aurora session's config

Log out and in again afterwards. Your files are not touched.

Logs

WhatWhere
The whole system and your sessionjournalctl -b, journalctl --user -b, or the Logs app
Aurora Shell$XDG_RUNTIME_DIR/aurora-shell.log
Why the Aurora session fell back~/.local/state/aurora/compositor-failure.log
The installer~/.cache/calamares/session.log in the live session: copy it somewhere (a USB stick) before restarting, since the live session forgets everything
SnapshotsTimeshift's log in Timeshift
Show screenshot
System Health: diagnostics and suggested actions.
System Health: diagnostics and suggested actions.

Click the image to view it at full size.