fds-os/docs/troubleshooting.md

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.
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, 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; 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. Rebooting uses a new session directory; existing DATA overlays remain in the old session and can be exported.