🛠️ Troubleshooting Guide

Docker Desktop fails to launch or shows an error on startup.

1. Restart your computer — this resolves most Docker startup failures
2. Check that virtualization is enabled in BIOS (required on Windows)
3. On Windows: ensure WSL2 is installed and set as default
4. Re-install Docker Desktop if the above doesn't help

Copy# Windows — check WSL2
wsl --list --verbose
wsl --set-default-version 2

The Docker CLI can't reach the Docker daemon — usually means Docker Desktop isn't running.

1. Open Docker Desktop and wait for it to show "Docker is running"
2. Then re-run your docker command

Copy# Verify Docker is running
docker info

The container starts but immediately exits or restarts in a loop.

Copy# Check container logs
docker logs agent-zero

# Check exit code
docker inspect agent-zero --format='{{.State.ExitCode}}'

Common causes: missing API key env var, port already in use, insufficient memory. Check the logs for the specific error.

Pulling the Agent Zero image takes forever or times out.

Copy# Try pulling again (resumes partial downloads)
docker pull alexander-ai/agent-zero:latest

# Or pull a specific version
docker pull alexander-ai/agent-zero:v0.9

Browser shows "This site can't be reached" or connection refused.

1. Verify the container is running: docker ps | grep agent-zero
2. Check the port mapping is correct: should show 0.0.0.0:50001->80/tcp
3. Try http://127.0.0.1:50001 instead of localhost
4. Check if something else is using port 50001

Copydocker ps
# Look for: 0.0.0.0:50001->80/tcp

# Check what's on that port
# Windows:
netstat -ano | findstr :50001
# macOS/Linux:
lsof -i :50001

Another process is occupying port 50001. Use a different port.

Copy# Use port 50002 instead
docker run -p 50002:80 alexander-ai/agent-zero

# Then access at:
# http://localhost:50002

Agent Zero can't authenticate with your LLM provider.

1. In Agent Zero's Settings panel, verify your API key is pasted correctly — no leading/trailing spaces
2. Make sure the key is for the correct provider (OpenAI key for OpenAI models, etc.)
3. Check the key is active in your provider dashboard
4. Ensure you have billing set up — most providers require a payment method even for free tiers

You've hit your API rate limit or usage quota.

• OpenAI: Add a credit card and set a spending limit at platform.openai.com/billing
• Anthropic: Check console.anthropic.com for usage limits
• OpenRouter: Add credits at openrouter.ai/credits — or switch to a free model

Tasks hang, responses take minutes, or nothing happens after submitting a task.

• Check your internet connection — Agent Zero needs to reach your LLM provider's API
• Try a faster/smaller model (GPT-4o-mini vs GPT-4o, Claude Haiku vs Claude Opus)
• Check provider status pages for outages
• Restart the container: docker restart agent-zero

Copydocker restart agent-zero

The model name you entered isn't recognized by the provider.

• Double-check the exact model ID in Agent Zero settings (e.g. gpt-4o not gpt4o)
• Some models require specific API access tiers — check your provider account
• For OpenRouter, find the exact model slug at openrouter.ai/models

Docker Desktop on Windows requires WSL2. Run these commands in PowerShell as Administrator:

Copy# Install WSL2
wsl --install

# Set WSL2 as default
wsl --set-default-version 2

# Restart your PC after installation

Docker needs hardware virtualization enabled in BIOS/UEFI.

1. Restart your computer and enter BIOS (usually Del, F2, or F10 during boot)
2. Look for "Virtualization Technology", "VT-x", or "AMD-V" and enable it
3. Save and exit BIOS, then restart

Some software (VirtualBox, VMware older versions) conflicts with Hyper-V which Docker uses.

Copy# Run in PowerShell as Administrator
# Enable Hyper-V
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All

If using VirtualBox: update to 6.1+ which supports running alongside Hyper-V.

Docker images built for x86 run under Rosetta emulation on Apple Silicon, which is slower.

Copy# Pull the ARM-native image if available
docker pull --platform linux/arm64 alexander-ai/agent-zero:latest

# Or force x86 with Rosetta
docker pull --platform linux/amd64 alexander-ai/agent-zero:latest

macOS may ask for permission to allow Docker to make changes.

• Click "Allow" when macOS asks for system extension permission
• Go to System Settings → Privacy & Security → approve Docker if prompted
• Restart Docker Desktop after granting permissions

Your user isn't in the docker group. You're running docker without sudo.

Copy# Add your user to the docker group
sudo usermod -aG docker $USER

# Log out and back in, then verify
groups $USER | grep docker

# Or use sudo for now
sudo docker run -p 50001:80 alexander-ai/agent-zero

Copy# Start Docker service
sudo systemctl start docker

# Enable on boot
sudo systemctl enable docker

# Check status
sudo systemctl status docker

Agent Zero's memory is stored inside the container. If you remove the container, memory is lost.

Copy# Mount a local folder to persist memory across restarts
docker run -p 50001:80 \
  -v ~/agent-zero-data:/a0 \
  alexander-ai/agent-zero

If something is badly misconfigured and you want a clean slate:

Copy# Stop and remove container
docker stop agent-zero
docker rm agent-zero

# Pull fresh image
docker pull alexander-ai/agent-zero:latest

# Start fresh
docker run -p 50001:80 --name agent-zero alexander-ai/agent-zero