3.4 KiB
Troubleshooting
Read the complete command error and its log before retrying. Build logs are in
out/logs/; emulator console.log and qemu.log are in the selected session.
On FDS, fds bay N, fds profiles and fds power status report the relevant
operation state. Append --help to a command for accepted options.
For physical Pi startup, use first-boot troubleshooting. For the Paperlike on HDMI plus USB, use Dasung diagnostics.
| Symptom | Resolution |
|---|---|
| Build disk is full | Stop builds and VMs; run make clean-preview, then make clean. See retention rules. |
| Missing host utility | Install the named utility or select the documented image/XBPS/QEMU runner. doctor checks image and emulator prerequisites. |
| Bubblewrap/user namespace failure | Check that the host permits unprivileged namespaces. Run the check in setup; do not switch software builds to root. |
| Void checkout is unprepared | Bootstrap the checkout using upstream xbps-src instructions, then select it with --void-packages. |
| Stale generated overlay/source package | Compare the source and generated copy. Preserve independent edits, remove only that generated copy, and retry. Never overwrite tracked upstream templates. |
| Output already exists | Use a new output directory, cartridge image or preview. A stopped emulator session can be restarted; see below. |
| Executable architecture or tree integrity error | Rebuild the source package and cartridge. FDS cannot run an invalid payload. |
| A command is unavailable | Wait for MOUNTED READ ONLY, inspect fds --json bay N, and use its qualified command alias. Run hash -r after removal if Bash retained an old path. |
| Empty or unconfigured physical bays | Run fds topology and calibrate the machine's bay map. Do not infer slots from disk names. |
| Duplicate cartridge ID | Give the second cartridge a distinct identity and rebuild it. |
| Console already in use | Detach the emulator console with Ctrl-] before guest, safe eject or shutdown. |
| Guest command timed out | Inspect the console log. It may still be running; do not repeat a write until its state is known. |
| Desktop activation fails | Inspect fds profiles and /run/log/xserver/current, /run/log/desktop/current. Check the display configuration. |
| Control panel cannot connect | Check /run/log/cartridged/current and that the cartridge service is running. The panel reconnects automatically. |
| Eject is blocked | Close programs, shells and extra mounts using the cartridge, then retry. Wait for SAFE before removal. |
| Shutdown is blocked | Read fds power status; resolve the reported storage problem and retry poweroff. fds power resume cancels a recoverable pending shutdown. |
| DATA needs checking | Use the recovery workflow; preserve a backup before repair where possible. |
To inspect cartridge service output on FDS:
tail -80 /run/log/cartridged/current
fds --json bay 01
To inspect a stopped emulator, read its saved logs directly on the workstation.
Run start again with the same session directory and boot options after stop.
Logs and DATA overlays are retained; bays start empty. Saved DATA can be
exported. If restart reports a live process,
check status and stop the existing VM before retrying.