Self-Hosted AI Stack — Part 7: Troubleshooting Appendix

NOTE

Each earlier part has its own specific troubleshooting section for problems in that domain. This appendix is different: it's a debugging method for when something's wrong and you're not yet sure which layer it's in — plus a quick index pointing back to the specific fixes.

A general debugging order for this stack

When something isn't working, check in this order rather than guessing randomly — each layer depends on the one below it, so it's rarely worth debugging Open WebUI's search integration if Docker itself isn't healthy.

1. Is the container even running?

docker ps

A container that's restarting in a loop or exited entirely won't show as healthy here. docker ps -a shows stopped ones too.

2. What do the logs actually say?

docker logs <container_name>

This is the single most under-used debugging step. Most "it just doesn't work" problems have an explicit error message sitting in the logs that immediately narrows down the cause — read this before changing any configuration.

3. Is the GPU actually reachable from inside the container?

docker exec -it <container_name> nvidia-smi

If this fails inside a container that's supposed to have GPU access, the problem is in Part 2's passthrough setup, not the service itself. Don't spend time debugging ComfyUI-specific settings if its container can't even see the GPU.

4. Can the containers reach each other?

Docker Compose puts all services in this stack on the same internal network, reachable by container name (not localhost). If one service can't reach another, confirm you're using the container name (e.g. http://ollama:11434, not http://localhost:11434) from inside another container's config.

5. Is it a port conflict on the host?

sudo ss -tulpn | grep <port>

If a service fails to start with a port-binding error, something else on the host already claimed that port.

Quick index by symptom

Symptom	Covered in
GPU not detected in a container	Part 2
WSL2 distro won't start or import fails	Part 2
`docker` commands require `sudo` every time	Part 2
Open WebUI shows no models	Part 3
Permission denied on mounted volumes	Part 3
SearXNG search returns nothing	Part 3
Duplicated limbs / warped anatomy in generated images	Part 4
Two generated subjects merge into one	Part 4
Inpainted region doesn't change at all	Part 4
Coding agent ignores your selected code	Part 5
Coding agent slow or editor freezes	Part 5
Remote `.ts.net` URL doesn't load	Part 6
Works locally but not remotely	Part 6

When to rebuild vs. restart

A quick restart (docker compose restart <service>) is enough for most transient issues — a service that hung, a connection that dropped. Reach for a full rebuild when you've changed the compose file itself, or when a restart doesn't clear the problem:

# Recreate containers without rebuilding images
docker compose down
docker compose up -d --force-recreate

# Rebuild images (only needed if you changed a Dockerfile)
docker compose down
docker compose up -d --build

WARN

docker compose down doesn't delete your data. As long as your volumes are bind-mounted to host folders (as they are throughout this series), tearing down and recreating containers doesn't touch your models, chat history, or checkpoints — those live on your host filesystem, not inside the container. Only worry about data loss if you also remove the mounted folders themselves.

Keeping the stack updated

Pull fresh images periodically rather than letting things silently drift out of date, especially for fast-moving projects like Open WebUI and ComfyUI:

docker compose pull
docker compose up -d

TIP

A stack that's working is worth more than being on the absolute latest version. Skim release notes for breaking changes before pulling updates, especially for ComfyUI, which changes its node ecosystem and menu structure often enough that a workflow built on an older version can occasionally need adjustment after an update.

That's the full series — from bare hardware to a working, remotely-accessible self-hosted AI stack with chat, coding assistance, and image generation. If you build this out and hit something not covered here, the troubleshooting pattern in this appendix is still the right starting point: check the layers from the bottom up, read the logs before changing configuration, and verify each component works in isolation before assuming the integration is at fault.