Troubleshooting: GUI, Docker, Volumes and Workspace Issues

Goal

Know the failure modes of the environment and their standard fixes, so a broken window never costs you an evening.

What You Will Build

A triage habit: doctor → GUI checks → volume/rebuild checks.

Why This Matters

Environment debugging is a real professional skill. The failure modes you meet here (X11/WSLg, container permissions, stale builds) are the same ones you will meet on lab PCs and industrial gateways.

Architecture Layer

Environment / tooling.

Files You Will Touch

• docs/docker_troubleshooting.md — the full reference this lesson summarizes.

Files You Should Not Touch Yet

—

Commands

./scripts/lab doctor                      # always first
# GUI (Ubuntu):
xhost +local: && echo $DISPLAY
# GUI (Windows/WSL):
ls /mnt/wslg && echo $DISPLAY
# Clean rebuild of the workspace only:
rm -rf build/ install/ log/ && ./scripts/lab build
# Full reset of containers:
docker compose -f docker/compose.yaml down --remove-orphans

Step-by-Step Instructions

Triage in this order:

1. ./scripts/lab doctor — fix FAILs first, they cascade.
2. GUI class (window does not appear): Ubuntu → xhost +local:; Windows → verify /mnt/wslg exists, else wsl --update from PowerShell and restart Docker Desktop.
3. Docker class ("cannot connect to daemon"): daemon not running or group membership missing — see the doc.
4. Volume/permission class (root-owned files, weird stale state): sudo chown -R $USER:$USER . then rebuild.
5. Workspace class ("package not found" after successful build): you are in a shell that did not source the overlay — new shells via the provided entrypoint do it automatically.
6. Still stuck → issue report with: OS, doctor output, exact command, full error.

What You Should See

Each class of problem has a two-minute standard response. Nothing here requires guessing.

How to Modify This for Your Own Application

When your own project breaks on someone else's machine, extend their doctor script instead of debugging by chat message. Every fix you apply twice belongs in a check.

Common Mistakes

• Skipping doctor and going straight to Stack Overflow.
• docker system prune -a as a first resort (it works, but you re-download gigabytes for what was an xhost issue).
• Editing docker/compose.yaml before understanding Module 2 — hold off.

Expected Output

None — reference knowledge.

Next Step

Module 0 checklist (checkpoints/module_00_checklist.md), then Module 1.