Quick Fixes for Common Setup Issues

Even with clear instructions, things sometimes go wrong during setup. This chapter provides quick solutions to the most common issues you might encounter when installing Docker, mise, or running your AI assistants. Keep this page bookmarked for reference.

Docker Issues

Issue: Docker Installation Fails on Intel-Based Processors

Symptoms:

• Error message: "Docker requires AVX2 instruction set"
• Container fails to start with "Illegal instruction" error
• PicoClaw or OpenClaw containers exit immediately

Cause: Older Intel processors (pre-2013) and some budget CPUs lack AVX2 support, which some Docker images require.

Solution:

1. Check if your CPU supports AVX2:

grep -o 'avx2' /proc/cpuinfo | head -1

If this returns nothing, your CPU does not support AVX2.

1. For PicoClaw: Use the compatible ARM64/x86 build:

# Download the appropriate binary instead of Docker
wget https://github.com/sipeed/picoclaw/releases/download/v0.1.1/picoclaw-linux-amd64
chmod +x picoclaw-linux-amd64
./picoclaw-linux-amd64 onboard

1. For OpenClaw: Use Node.js directly instead of Docker:

# Install Node.js first (see mise installation below)
curl -fsSL https://openclaw.ai/install.sh | bash

Prevention: When choosing a VPS, verify the CPU generation. Most modern VPS providers (NetCup, Hetzner, Hostinger) use recent Intel or AMD processors with full AVX2 support.

---

Issue: Docker Permission Denied

Symptoms:

• Error: "Got permission denied while trying to connect to the Docker daemon"
• Cannot run docker ps without sudo

Solution:

1. Add your user to the docker group:

sudo usermod -aG docker $USER

1. Log out and log back in (or use newgrp docker to apply immediately):

newgrp docker

1. Verify the fix:

docker ps

---

Issue: Port Already in Use

Symptoms:

• Error: "Bind for 0.0.0.0:18789 failed: port is already allocated"
• Cannot start containers that expose ports

Cause: Another service is already using the port that OpenClaw or PicoClaw wants to bind to.

Solution:

1. Find what is using the port:

sudo lsof -i :18789
# or
sudo netstat -tulpn | grep 18789

1. Either stop the conflicting service or use a different port:

For OpenClaw:

# Use a different port (e.g., 8080 instead of 18789)
openclaw gateway --port 8080

For PicoClaw Docker:

# In docker-compose.yml, change the port mapping:
ports:
  - "8080:18800"  # Host 8080 maps to container 18800

Prevention: Check port availability before starting services:

# Quick port check function
check_port() {
  if lsof -Pi :$1 -sTCP:LISTEN -t >/dev/null ; then
    echo "Port $1 is in use"
  else
    echo "Port $1 is available"
  fi
}

check_port 18789
check_port 18800

---

Mise Installation Issues

Issue: Mise Install Fails on Arch Linux / Omarchy

Symptoms:

• Error during mise install on Arch-based distributions
• Missing dependencies or compiler errors

Cause: Arch Linux requires updated system packages before installing mise.

Solution:

1. Update all system packages first:

sudo pacman -Syu

1. Install required dependencies:

sudo pacman -S base-devel openssl zlib

1. Then install mise:

curl https://mise.run | sh

For Omarchy Users: Omarchy is a pre-configured Arch Linux setup. It should have most dependencies, but if you encounter issues:

# Ensure Omarchy packages are up to date
omarchy-update

# Install mise via pacman if the curl method fails
yay -S mise

---

Issue: Mise Command Not Found After Installation

Symptoms:

• mise: command not found after running install script
• Cannot use mise to manage Node.js versions

Solution:

1. Add mise to your shell:

For Bash:

echo 'eval "$(~/.local/bin/mise activate bash)"' >> ~/.bashrc
source ~/.bashrc

For Zsh:

echo 'eval "$(~/.local/bin/mise activate zsh)"' >> ~/.zshrc
source ~/.zshrc

For Fish:

~/.local/bin/mise activate fish >> ~/.config/fish/config.fish

1. Verify installation:

mise --version

---

Container Runtime Issues

Issue: Container Exits Immediately

Symptoms:

• Docker container starts then stops immediately
• docker ps shows no running containers
• Logs show errors and exit code

Solution:

1. Check container logs:

# For the most recent container
docker logs $(docker ps -lq)

# For a specific container
docker logs <container_name>

1. Common fixes:

Missing configuration:

# For PicoClaw, ensure config is initialized
mkdir -p ~/.picoclaw
docker run -v ~/.picoclaw:/root/.picoclaw sipeed/picoclaw onboard

Permission issues:

# Fix ownership of mounted volumes
sudo chown -R $USER:$USER ~/.picoclaw

Out of disk space:

# Check disk usage
df -h

# Clean up Docker images
docker system prune -a

---

Issue: High Memory Usage

Symptoms:

• VPS becomes unresponsive
• OOM (Out of Memory) killer terminates processes
• System using swap heavily

Solution:

1. Check current memory usage:

free -h

1. Add swap space (temporary solution):

# Create 2GB swap file
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# Make permanent
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

1. Limit container memory:

For Docker Compose:

services:
  picoclaw:
    image: sipeed/picoclaw
    mem_limit: 100m
    memswap_limit: 100m

1. Long-term solution: Upgrade your VPS to have more RAM.

---

Network and Connectivity Issues

Issue: Cannot Reach Services from Outside

Symptoms:

• Services work locally on the VPS but not from your computer
• Connection timeout when trying to access web dashboard
• Cannot connect messaging apps to the gateway

Solution:

1. Check firewall status:

sudo ufw status
# or
sudo iptables -L

1. Open required ports:

# For OpenClaw (port 18789)
sudo ufw allow 18789/tcp

# For PicoClaw Web UI (port 18800)
sudo ufw allow 18800/tcp

# For SSH (essential!)
sudo ufw allow 22/tcp

1. Verify the application is binding to all interfaces:

For OpenClaw:

// In ~/.openclaw/openclaw.json
gateway: {
  host: "0.0.0.0",  // Not "127.0.0.1"
  port: 18789
}

For PicoClaw Docker:

# docker-compose.yml should expose ports correctly
ports:
  - "0.0.0.0:18800:18800"

1. Check VPS provider firewall (some providers have external firewalls):

• NetCup: Check SCP (Server Control Panel) firewall settings
• Hetzner: Check Hetzner Console firewall
• Hostinger: Check hPanel firewall settings

---

Issue: Slow Network Performance

Symptoms:

• AI responses take a long time
• Media uploads/downloads are slow
• Timeouts when connecting to AI APIs

Solution:

1. Test your VPS network speed:

# Install speedtest-cli if needed
curl -s https://install.speedtest.net/app/cli/install.deb.sh | sudo bash
sudo apt-get install -y speedtest

# Run test
speedtest

1. Check latency to AI providers:

# Test latency to OpenAI
ping api.openai.com

# Test latency to Anthropic
ping api.anthropic.com

1. Consider VPS location: Choose a VPS region close to your AI provider's servers:

• OpenAI: US-based (San Francisco, Virginia)
• Anthropic: US-based
• For EU users, some latency is unavoidable

---

Quick Reference: Common Error Messages

Error Message	Likely Cause	Quick Fix
permission denied while trying to connect to Docker daemon	User not in docker group	sudo usermod -aG docker $USER
port is already allocated	Port conflict	Use different port or stop conflicting service
no space left on device	Disk full	docker system prune -a or upgrade VPS
command not found: mise	Shell not configured	Add eval "$(~/.local/bin/mise activate bash)" to shell config
Illegal instruction (core dumped)	CPU lacks AVX2	Use native binary instead of Docker
connection refused	Firewall blocking	sudo ufw allow <port>/tcp
cannot assign requested address	Wrong host binding	Change from 127.0.0.1 to 0.0.0.0

Prevention Checklist

Before starting installation:

• Verify VPS has sufficient RAM (1GB+ for OpenClaw, 512MB+ for PicoClaw)
• Check CPU supports AVX2 (for Docker on older Intel): grep avx2 /proc/cpuinfo
• Ensure at least 5GB free disk space: df -h
• Confirm you have sudo/root access
• Note which ports are available: sudo lsof -i -P -n | grep LISTEN

When to Seek Help

If you encounter issues not covered here:

1. For OpenClaw issues:

   • Documentation: https://docs.openclaw.ai/
   • Check the troubleshooting section of the docs

2. For PicoClaw issues:

   • Documentation: https://docs.picoclaw.io/
   • GitHub Issues: https://github.com/sipeed/picoclaw/issues

3. For ThinkCodeShip guide issues:

   • Contact support with your specific error message
   • Include output from docker logs or application logs

---

Next: Why Containerized Installation Matters - Understanding Docker's importance for security and deployment.