Troubleshooting
Find your symptom below. Most problems come from something the computer lacks, which
wazza --check names with its fix, or from a key or memory running out.
First step for anything about starting: run wazza --check in a terminal. It checks KVM,
the systemd user session, the display, the Chat sandbox, the graphics driver and the VM display buffers, and prints
the commands that fix what is missing (What is checked).
The window does not open#
- No X11 display: Wazza OS's window needs X11, which Wayland desktops give through XWayland.
wazza --checknames the package to install for your distribution (for examplesudo apt install xwayland). - Already running: a second start only brings the running window to the front. Look for it on another workspace or screen.
- On a server, start it with its own screen: Wazza OS on a server.
The VM does not start#
| What you see | Why | Fix |
|---|---|---|
| The check says Hardware virtualization (KVM) is missing | Virtualization is off in the firmware,
or your user may not use /dev/kvm | Turn on VT-x (Intel) or SVM (AMD) in your computer's
firmware settings; sudo usermod -aG kvm "$USER", then log out and in |
| The check says systemd user session is missing | Each VM runs in a memory-capped part of your user session | Log in through your desktop; on a server, loginctl enable-linger "$USER" |
| The check says VM display buffers is missing | The VM's picture needs larger system buffers | sudo sysctl -w net.core.rmem_max=4194304 net.core.wmem_max=4194304 (the package sets it at boot) |
| Not enough free memory to start the VM | Too little memory is free for its desktop | Close one or two of the apps the card names, then start again (When memory is short) |
| It stays starting for long | The first start of a VM prepares its disk and takes longer than the next ones | Wait; then Settings › Virtual machines › Restart (This window shows) |
| Your disk is full | The VM's disk grows as it writes | Free space on your computer (Disk space) |
A Chat does not answer#
- No key or sign-in: Wazza OS comes without an AI key. A Chat on Hermes then answers at once Add an OpenRouter key under Sign In › API keys, or sign in to your Wazza account: add a key, sign in to your Wazza OS account, or log in with a plan you pay for (Sign in, keys and plans).
- A model your keys do not reach: a Chat keeps the model it started with. If no key or account of yours reaches it, the Chat says which one it needs: This model runs on an OpenRouter key: add one under Sign In › API keys, or pick a Wazza model, or This model runs on your Wazza account: sign in to it, or pick an OpenRouter model. Add it, or pick another model in the Chat's model window (Choose the agent and the model).
- Out of credit or rate-limited:
wazza --gui provider-keys list --creditshows what OpenRouter and DeepSeek keys have left. Add a second key or account: when one runs out, the next takes over (Several keys or accounts). - A long job: a command an agent runs may take up to 10 minutes before it is stopped (Time limits). The Chat's steps show what it is doing; the stop button stops it.
- Chats on your computer do not start (Claude Code, Codex…): the check's Chat sandbox
line is missing or limited. Its fixes reload Wazza OS's AppArmor profile or allow user namespaces, for example
sudo apparmor_parser -r /etc/apparmor.d/wazza-bwrap.
An app tab stays black or frozen#
Wait a moment if the app is starting: the tab says so, and large apps take a while the first time.
Right-click the tab › Reload: the tab's app starts again (The tab menu).
Reset the picture between Wazza OS and the tab, without touching the app: ask the tab's Chat to "recover this tab", or run
wazza --gui drive recover --tab TAB.Look at the VM card at the bottom of Home: if the VM is not running, start or restart it in Settings › Virtual machines.
Every app slow or black: check the graphics. The VM card's last line names your graphics card; llvmpipe there means software graphics.
wazza --check's Graphics driver line says what to fix; to rule the card out, set Settings › VM resources › Graphics › GPU to None (CPU only) and restart the VM (When 3D is slow).
An app does not install#
- The tab says why, with Retry installation and Show log; Wazza OS already retried once by itself. Most failures are the VM's Internet connection or a download server that is down: retry later.
- The VM's disk or memory is full: see Memory, CPU and disk.
- An app you added: its install script failed; read the log, fix the script in Edit app… and install again (Edit an app).
Files do not copy#
- Settings › Files & sharing: a direction set to Off copies no files (text still copies). With Ask, look for the question (Files & sharing).
- Files from the VM land in
Downloads/From the VMon your computer, as new files, never over yours. - An agent can copy only files below your home folder, and no hidden ones.
No sound#
- Only the tab you are on is heard. Check that tab's menu › Sound (muted, volume).
- The VM's sound needs the Sound card drivers tool, installed on the first start: Apps › System; install it again if it is missing.
- Your computer's own output and volume apply as for any app.
Everything is slow#
- Your computer is short of memory: close apps and tabs you do not use (Memory, CPU and disk).
- The VM may use too few processors for heavy work: raise them in VM resources.
- 3D apps: When 3D is slow.
- The window itself: lower Max frame rate, set Glass to Off.
Sign-in problems#
- A plan login opens your browser: finish it there, then come back; an attempt that is not finished in time ends by itself, and you can start again.
- An API key is refused when it is checked: copy it again from your provider's site, whole, with no space.
- Several accounts: the order and the rotation are on the Sign in page (Several keys or accounts).
Updates#
- Each message of the Update page, with what to do: What the messages mean.
- The update downloads but does not install: Install Now needs your confirmation, then your administrator password. Keep Wazza OS's window in front while you confirm.
- The page cannot reach the update server: check your connection. You can always update with the install command,
or download the package from
https://os-downloads.wazza.aiand install it over your version (Install › Update). - After an update, restart Wazza OS: until then the old version keeps running.
Never remove the Wazza OS package to reinstall it: removing it deletes your Wazza OS data (VMs, Chats, settings). Install the new package over the old one.
Start fresh#
- Show the first start's steps again:
wazza --gui setup reset-first-run, then restart Wazza OS. - Reset one VM other than vm-1, or remove it: Settings › Virtual machines (Remove or reset a VM).
- Remove all of Wazza OS's data on this computer and start like the first time: Settings › This computer › Remove all data.
Send feedback#
Home › Feedback: say what happened and what you expected. Wazza OS adds its version, never your account (Feedback). For a problem with an agent, say which tab, which agent and model, and what you asked.