07. API Connection Refused
Checklist Before Assuming a Code Bug
- Is the server process running?
ps aux | grep ollamaorps aux | grep vllm - Is the correct port in use?
sudo lsof -i :11434 - Is the firewall allowing connections?
sudo ufw statusorsudo iptables -L - Is the server binding to the right interface? Some servers bind to
127.0.0.1by default, accepting only local connections.
Common Causes
Wrong Host Binding
Ollama binds to 127.0.0.1 by default. External access requires:
# Check current binding
sudo lsof -i :11434 | grep LISTEN
# If bound to 127.0.0.1, restart with correct host
OLLAMA_HOST="0.0.0.0" ollama serve
Port Already in Use
# Find what's using the port
sudo lsof -i :8080
# Kill the process
sudo kill $(sudo lsof -t -i :8080)
Docker Network Isolation
# Check if container can reach host
docker exec -it <container_id> curl http://host.docker.internal:8080/health
# Run container with host network
docker run --network host your-ai-service
TLS Certificate Issues
# Test HTTP (non-TLS) connectivity
curl http://localhost:11434/api/tags
# Test with verbose output
curl -v http://localhost:11434/api/tags
Local verification checkpoint
Run the smallest example from this chapter in a local workspace and record the package version, runtime, data path, and observed output. If the result depends on model size, vector count, CPU/GPU backend, or available memory, note that constraint beside the exercise so the lesson remains reproducible.
Local verification checkpoint
Run the smallest example from this chapter in a local workspace and record the package version, runtime, data path, and observed output. If the result depends on model size, vector count, CPU/GPU backend, or available memory, note that constraint beside the exercise so the lesson remains reproducible.
Start an Ollama server, verify it works locally, then deliberately misconfigure it to bind to 127.0.0.1 while attempting to connect from the host machine. Observe the exact error message. Restore correct configuration.