Troubleshooting
Common first-run and QEMU issues
just setup Fails
Check the tool named in the error:
| Symptom | Fix |
|---|---|
rustup is required | Install rustup, then rerun just setup |
| Go missing or too old | Install Go >= 1.22 and rerun just setup |
| Go module download fails | Check network access or pre-populate the Go module cache |
| Rust target missing | Let just setup install the pinned target |
Limine Download Fails
The ISO build downloads the pinned Limine binary release into
third_party/limine and verifies the tarball hash. In offline environments,
pre-populate that directory with the Limine binaries required by the build.
limine-bios.sys
limine-bios-cd.bin
limine-uefi-cd.bin
BOOTX64.EFI
limineNo Hardware Acceleration
If /dev/kvm is not usable on Linux, or HVF is not available on macOS, the QEMU
wrapper switches to TCG with -cpu max. That is expected but slower.
For deterministic replay debugging, TCG is required. For day-to-day interactive use, prefer KVM or HVF when available.
QEMU Display Errors
Check backend support:
qemu-system-x86_64 -display helpThen force a backend:
QEMU_DISPLAY=sdl just boot-fast
QEMU_DISPLAY=gtk just boot-fast
QEMU_DISPLAY=cocoa just boot-fastOn macOS, Cocoa is the default. GTK is usually not available there.
Boot Hangs Or Looks Blank
Start with serial output:
just boot-log
tail -n 120 test_output.logThen skip the wheel and enable debug logs:
DEBUG=1 just boot-fast
BOOT_CMDLINE='tests=off roulette=skip boot.debug=on' just boot-logFor a freeze, use just boot-debug, then run just debug-bt in another
terminal to capture all-CPU backtraces into builddir/freeze-gdb.log.
Tests Fail In QEMU
Use the harness options before dropping to raw serial:
just test-rerun-failed
just test-verbose FILTER='slopos_mm::*'
just test-json builddir/events.jsonl
just test-rawIf the failure is a memory corruption and it reproduces under TCG single-core, record it:
just rr-record
just rr-gdb WATCH=0xdeadbeef