40 lines
3.2 KiB
Markdown
40 lines
3.2 KiB
Markdown
# 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.
|
|
|
|
| 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, preview or emulator session. Creation does not overwrite existing outputs. |
|
|
| 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.
|