Skip to content

Troubleshooting

This page is organized by symptom — what you actually see or experience — rather than by component. If you already know which subsystem is broken, skip ahead to KNOWN_ISSUES.md for a curated list of bugs and workarounds.

If nothing here helps, jump to the diagnostic-capture section at the bottom and file a report via SUPPORT.md.

USB won't boot on this machine

Symptom: The machine powers on and goes straight to Windows, macOS, or the existing Linux install. The PAI boot menu never appears.

Likely causes:

  1. Boot order in firmware still prefers the internal disk.
  2. Secure Boot is enabled and blocking the USB.
  3. The USB was flashed with a wrong or corrupted image.

Fix:

  • Enter the firmware setup (usually F2, F10, F12, Del, or Option depending on vendor) and move USB devices above the internal disk in the boot order.
  • Temporarily disable Secure Boot. PAI signs its shim but not every machine accepts it on first try; once you've booted, you can re-enable Secure Boot with enrolled keys.
  • Re-verify the image checksum (see docs/installation.md) and re-flash if it does not match.

Still stuck? See SUPPORT.md.

Boots to host OS instead of PAI

Symptom: The firmware appears to accept the USB but the host's bootloader (GRUB, systemd-boot, Windows Boot Manager) loads instead of PAI.

Likely causes:

  1. The USB is being chain-loaded from the internal disk rather than booted directly.
  2. Fast Boot / Quick Boot is skipping the USB enumeration phase.
  3. The USB is flashed as a data partition, not a bootable image.

Fix:

  • Use the firmware's one-time boot menu (often F12 or F9) and pick the USB device explicitly.
  • Disable Fast Boot / Quick Boot in firmware.
  • Re-flash using the steps in docs/USB-FLASHING.md; do not drag-and-drop the ISO.

Still stuck? See SUPPORT.md.

Black screen / no Sway session

Symptom: The kernel boots and you see some log lines, but the display goes black and no Sway compositor starts.

Likely causes:

  1. GPU driver (typically NVIDIA proprietary) is not matched to the kernel on this machine.
  2. Wayland is failing on a hybrid-GPU laptop.
  3. The session crashed after login and dropped you on an inactive TTY.

Fix:

  • Switch to a TTY with Ctrl+Alt+F2 and log in. Run journalctl -b -p err to see errors. If the driver is the issue, boot with the nomodeset kernel parameter from the PAI boot menu.
  • On hybrid-GPU laptops, try the Integrated-GPU only boot entry.
  • If you landed on a TTY, systemctl --user restart sway (or reboot) often recovers a one-off session crash.

Still stuck? See KNOWN_ISSUES.md.

Wi-Fi not detected

Symptom: The network applet shows no wireless interfaces, or iwctl device list prints an empty table.

Likely causes:

  1. The Wi-Fi chipset needs non-free firmware not present on this image.
  2. A hardware kill switch (Fn key or physical slider) is off.
  3. The interface is blocked by rfkill.

Fix:

  • Check rfkill list and unblock with rfkill unblock all.
  • Toggle the hardware Wi-Fi switch; many laptops need Fn+F2 or similar.
  • Identify the chipset with lspci -k | grep -iA2 net and check KNOWN_ISSUES.md for firmware packages to include in your next flash.

Still stuck? See SUPPORT.md.

Ollama is extremely slow

Symptom: Prompts take 30+ seconds per token, or the model appears to stall entirely.

Likely causes:

  1. The model is running on CPU instead of GPU.
  2. System memory is exhausted and the OS is swapping.
  3. You picked a model too large for this hardware.

Fix:

  • Confirm GPU use with ollama ps; the output should list a GPU backend, not cpu. If it says cpu, ensure the proprietary GPU driver loaded (lsmod | grep -i nvidia or the equivalent) and restart Ollama.
  • Close other heavy apps. Browsers and LLMs compete for memory.
  • Try a quantized variant (:q4_K_M instead of :f16) or a smaller model. See BENCHMARKS.md for per-hardware guidance.

Still stuck? See docs/usage/ollama.md or SUPPORT.md.

Ollama reports out of memory

Symptom: ollama run exits immediately with a CUDA or Metal out-of-memory error, or the session is killed by the OOM-killer.

Likely causes:

  1. Model weights exceed available VRAM.
  2. Context window is too large for this model on this GPU.
  3. Another GPU process is holding memory.

Fix:

  • Pick a smaller quantization or a smaller model.
  • Lower the context window via OLLAMA_CONTEXT_LENGTH or the model's num_ctx parameter.
  • Check nvidia-smi (or radeontop) for other processes and close them.

Still stuck? See KNOWN_ISSUES.md.

Persistence won't unlock

Symptom: At boot, the persistence prompt rejects your passphrase, or the persistence volume is not offered at all.

Likely causes:

  1. Wrong passphrase (keyboard layout mismatch is common — the prompt runs before your chosen layout loads).
  2. LUKS header is corrupted.
  3. The persistence partition was not initialized on this USB.

Fix:

  • Re-enter the passphrase using US QWERTY even if you normally use a different layout. The pre-boot environment uses US keys.
  • If you backed up the LUKS header (strongly recommended — see the tutorial), restore it with cryptsetup luksHeaderRestore.
  • If persistence was never set up on this stick, follow the setup flow in docs/usage/.

Still stuck? A corrupted header with no backup usually means data loss. File a report via SUPPORT.md only for diagnostics — the data itself cannot be recovered.

Tor won't connect

Symptom: The Tor indicator stays red, or tor exits with bootstrapping errors.

Likely causes:

  1. The network blocks direct connections to the Tor network.
  2. System clock is wrong; Tor rejects handshakes with large clock skew.
  3. A captive portal has not been completed yet.

Fix:

  • Sync the clock: sudo chronyc makestep (or reboot with network reachable).
  • Complete any captive portal login first, then start Tor.
  • If direct connections are blocked, configure a bridge (obfs4 or snowflake) in the Tor settings panel.

Still stuck? See KNOWN_ISSUES.md.

Firefox won't start / wrong policy

Symptom: Firefox opens and immediately closes, or it starts but is missing the hardened PAI policy (no proxy, permissive permissions).

Likely causes:

  1. A stale profile from a previous PAI version is incompatible.
  2. The policy file under /etc/firefox/policies/ was not mounted.
  3. Another Firefox instance is already holding the profile lock.

Fix:

  • Close all Firefox windows and remove ~/.mozilla/firefox/*/lock.
  • Start Firefox from a terminal (firefox --no-remote -P) and create a fresh profile if the old one is incompatible.
  • Confirm the policy is active: visit about:policies — you should see PAI's entries. If empty, the policy file is missing; reinstall or re-flash.

Still stuck? See SUPPORT.md.

Crypto wallet won't sync

Symptom: An Electrum/Sparrow/other wallet cannot reach the network, or sync stalls at 0%.

Likely causes:

  1. The wallet is trying to use Tor, and Tor has not bootstrapped yet.
  2. Firewall rules are blocking the wallet's outbound port.
  3. You are on a restrictive network (hotel Wi-Fi, corporate proxy).

Fix:

  • Confirm Tor is green before starting the wallet, or disable Tor routing for the wallet if you are deliberately using clearnet.
  • Check sudo nft list ruleset (or the firewall GUI) for drops.
  • Try tethering from a phone to rule out the network.

Still stuck? See KNOWN_ISSUES.md.

Screen brightness / suspend / lid-close glitches

Symptom: Brightness keys do nothing, lid-close doesn't suspend, or the machine wakes up with a black screen.

Likely causes:

  1. ACPI quirks on this laptop model.
  2. logind rules differ from what the vendor expects.
  3. GPU driver loses state across suspend.

Fix:

  • For brightness, try brightnessctl set 50% directly; if that works, the keybinding is missing — remap it in ~/.config/sway/config.
  • For lid-close, edit /etc/systemd/logind.conf and set HandleLidSwitch=suspend, then systemctl restart systemd-logind.
  • For suspend/resume blackness, add nvidia.NVreg_PreserveVideoMemoryAllocations=1 to kernel params (NVIDIA) or the equivalent for your GPU.

Still stuck? See KNOWN_ISSUES.md.

ARM64-specific issues (RPi first-boot quirks)

Symptom: On a Raspberry Pi, the first boot hangs at the rainbow splash, or networking comes up but HDMI does not, or USB peripherals are not detected.

Likely causes:

  1. Power supply is underspec'd (common cause of boot hangs on RPi 4/5).
  2. HDMI hotplug detection failed; the Pi chose the wrong output.
  3. The microSD / USB storage is slow or worn.

Fix:

  • Use the official RPi power supply, or one rated for the full current draw. Brownouts cause silent hangs.
  • Force HDMI on by setting hdmi_force_hotplug=1 in /boot/firmware/config.txt.
  • Test on another storage device; SD cards degrade and slow boots dramatically.
  • For RPi 5, ensure you flashed the ARM64 image, not ARMv7.

Still stuck? See KNOWN_ISSUES.md.

If none of the above worked

Capture diagnostics before rebooting — much of the useful state is volatile.

From a terminal:

mkdir -p ~/pai-diag && cd ~/pai-diag
uname -a                      > uname.txt
cat /etc/os-release           > os-release.txt
journalctl -b --no-pager      > journal-current.txt
journalctl -b -1 --no-pager   > journal-previous.txt 2>/dev/null || true
lspci -k                      > lspci.txt
lsusb                         > lsusb.txt
ip addr                       > ip-addr.txt
rfkill list                   > rfkill.txt
ollama ps                     > ollama.txt 2>/dev/null || true
tar czf ~/pai-diag.tgz -C ~ pai-diag

Before sharing, review the files. Journals can contain network names, paths, and hostnames. Redact anything sensitive. Never share your LUKS header, wallet files, or ~/.ssh/.

File a report following SUPPORT.md, attaching pai-diag.tgz. If the issue is a confirmed bug, also open an entry in KNOWN_ISSUES.md via PR.