# 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](hardware-setup.md#when-the-first-boot-fails).
For the Paperlike on HDMI plus USB, use [Dasung diagnostics](dasung.md#diagnose-a-connection-problem).

| Symptom | Resolution |
| --- | --- |
| Build disk is full | Stop builds and VMs; run `make clean-preview`, then `make clean`. See [retention rules](cleanup.md). |
| 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](getting-started.md); 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](recovery.md); preserve a backup before repair where possible. |

To inspect cartridge service output on FDS:

```sh
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](workstation.md#save-emulator-data). If restart reports a live process,
check `status` and stop the existing VM before retrying.