The things that go wrong, and what they usually are.

Start by ruling out the download

A truncated or badly written USB stick does not announce itself — it installs a system with corrupt files and then fails in ways that look like anything but a bad download. Two checks, both cheap:

• Verify the ISO against the published checksum before writing it. The command for your system is on the install steps, and the digest is at /download.sha256.
• Boot the stick and choose Check the installation medium for defects from the GRUB menu. It verifies every staged file and stops with a message rather than booting a broken system.

It will not boot from the stick

• Secure Boot must be off. VolnOS's boot files are not signed with Microsoft's key, so a machine that enforces Secure Boot refuses the medium — often with no useful message. Turn it off in firmware setup.
• Pick the UEFI entry. In the boot menu the same stick may appear twice; the UEFI one is the one that works.
• Try the safe-graphics entry. If it boots to a black screen or garbage, Try VolnOS (safe graphics) starts on the basic display driver.
• Write it in image mode. On Windows, Rufus and balenaEtcher must write the ISO as an image (DD), not extract it onto the stick.

The installer will not list my disk

The disk list hides nothing — an ineligible disk is shown with the reason beside it. The usual reasons:

• Too small. The target must be at least 16 GB.
• It is the stick you booted from. The live medium is excluded so it cannot erase itself mid-install.
• Read-only, or not a real disk — loop, ROM and zram devices are filtered out.

If you plugged the disk in after the installer started, say rescan and it will look again.

The assistant wants a model, or a key

• Ten questions a day are available with no key at all, as the row called VolnOS at the top of the model picker. They reset daily rather than accumulating.
• Your own key works with any of the listed gateways, or any other URL that speaks the OpenAI protocol. Paste the endpoint whole; the model list comes from whatever that endpoint reports.
• A model on your own machine — Ollama, LM Studio, llama.cpp or vLLM — usually needs no key. Choose A server on this machine or network and give it the address, typically http://localhost:11434/v1/chat/completions. Something has to already be running there: VolnOS ships no model.
• The installer needs a connection before it will start, because the assistant runs the install. Once it is writing, everything comes off the medium — losing the network mid-install cannot spoil the disk.

A Windows application misbehaves

Everything is set up already — Wine, winetricks, a prefix manager, file associations, and Mono and Gecko handled at build time so nothing prompts you. What remains is the application itself: Wine is a compatibility layer, not Windows.

• Look the application up in the WineHQ AppDB. It records which versions work and the workarounds that help.
• Give a troublesome application its own prefix in the prefix manager, so a tweak for one does not break another.
• Ask the assistant — windows_app_status is one of its read-tier tools, so it can look at the state of things without changing anything.

Updates

Control Panel → Updates checks and installs through apt, and asks for your password when it installs, because that is a privileged operation. If an update fails to fetch, the channel is unreachable rather than broken: apt verifies a GPG signature, so it refuses bad data instead of installing it.

The store status shows whether the update store is currently reachable from this site's point of view.

Still stuck

Open a ticket at VolnOS-Org/ticket — it is public, and a GitHub account is the only one you need. Prefer email? updates@volnos.org.

Useful things to include: what you were doing, what happened instead, the release from the badge at the top of this page, and whether it happens in the live session or on an installed system.