🔧 Troubleshooting

Docker Hub Blocked

Symptom: docker pull hello-world hangs forever or times out.

Cause: Docker Hub is blocked or throttled in China.

Fix:

1. Edit /etc/docker/daemon.json to add China mirrors
2. Restart Docker: sudo systemctl restart docker
3. Use ghcr.io for images that support it (Open WebUI)

Slow Model Downloads

Symptom: ollama pull qwen3:30b runs at 2 MB/s and takes 2+ hours.

Cause: Ollama downloads from international servers (likely Cloudflare R2 or similar).

Fix:

• Set timeout to 2 hours: timeout: 7200 in your automation tool
• Ollama resumes partial downloads automatically — if killed, just re-run the command
• Download overnight when network is less congested

Port 53 Conflict

Symptom: AdGuard Home container fails to start. docker-compose up errors with "port 53 already in use."

Cause: systemd-resolved owns port 53 on Ubuntu 24.04. You cannot bind it without stopping the system service first.

Fix options:

1. Map web UI only: Use port 3001 for AdGuard's web interface. DNS functionality requires manual client configuration or router-level DNS forwarding.
2. Disable systemd-resolved: sudo systemctl stop systemd-resolved && sudo systemctl disable systemd-resolved. Then map port 53 normally. May break some DNS resolution.
3. Use a different DNS port: Map 5353:53 and configure clients/router to use port 5353. Most clients don't support non-standard DNS ports easily.

We chose option 1. AdGuard web UI works on 3001. DNS filtering would need router cooperation.

Jellyfin Permissions

Symptom: Jellyfin container starts but shows "Server is starting..." forever. Logs show permission denied on /config.

Cause: Config/cache directories created as root, but Jellyfin runs as UID 1000.

Fix:

sudo chown -R 1000:1000 /home/wm/ai-stack/jellyfin/
docker-compose restart jellyfin

Ollama Update Killed

Symptom: curl -fsSL https://ollama.com/install.sh | sh gets SIGKILL at 78-91%.

Cause: The update script downloads a large binary (~400MB+) which gets killed by resource/timeout limits in the execution environment.

Fix:

• Current version (0.24.0) works fine with ROCm. No urgent need to update.
• If updating is critical, download the binary manually with curl (resumable) instead of the install script.
• Or update when network is better (at home, not school).

Timeshift + NTFS

Symptom: Timeshift snapshot fails with "cannot unmount /media/wm/2TB-Data" or creates empty snapshots.

Cause: Timeshift wants exclusive mount control. If the partition is auto-mounted via fstab, Timeshift can't get it.

Fix:

1. Set noauto in /etc/fstab for the target partition
2. Create a systemd oneshot service that mounts after local-fs.target
3. Enable the service: sudo systemctl enable mount-2tbdata.service

# /etc/systemd/system/mount-2tbdata.service
[Unit]
Description=Mount 2TB-Data partition
After=local-fs.target
Before=ollama.service

[Service]
Type=oneshot
ExecStart=/bin/mount /media/wm/2TB-Data
RemainAfterExit=yes

[Install]
WantedBy=multi-user.target

Compose Version Bug

Symptom: docker-compose up fails with "ContainerConfig: command not found" or similar.

Cause: docker-compose v1 (apt-installed) has a bug parsing newer image manifests that omit ContainerConfig.

Fix:

• Use docker run directly as a workaround
• Or install docker-compose v2 plugin: sudo apt install docker-compose-plugin
• Or use docker compose (space, not hyphen) if v2 is installed

WeCom on Ubuntu

Symptom: WeCom (企业微信) desktop client fails to install or extract.

Cause: The UOS/Deepin Wine compatibility layer is unreliable on some Ubuntu setups.

Fix:

1. Use the web version: https://work.weixin.qq.com/ — most reliable on Linux
2. For full features (calls), use your phone or an Android emulator
3. WeChat desktop (personal) works fine — only WeCom (enterprise) has issues