How to Fix Open-WebUI 'Ollama Connection Failed' Errors in Docker

Overview

When pairing Open-WebUI with Ollama in a Dockerized environment, users frequently encounter errors like “Ollama Connection Failed”, “HTTP 502 Bad Gateway”, or “WebUI WebUI Host Not Found”.

This issue almost universally stems from improper Docker container networking defaults: specifically, attempting to connect Open-WebUI to http://localhost:11434 when Ollama is running inside a separate container or directly on the host interface.

This guide provides exact network topology fixes for both single-host Docker deployments and isolated container networks.

---

Root Cause Analysis

Inside a Docker container, localhost (or 127.0.0.1) refers strictly to the container’s isolated loopback interface—NOT the host machine’s IP address.

┌────────────────────────────────────────────────────────┐
│                      HOST MACHINE                      │
│                                                        │
│  ┌────────────────────────┐  FAILED WRONG PATH         │
│  │ Open-WebUI Container   │ ────► http://localhost:11434 (Refers to itself!)
│  └────────────────────────┘                            │
│                                                        │
│  ┌────────────────────────┐  CORRECT DOCKER BRIDGE     │
│  │ Ollama Container       │ ◄───► http://ollama:11434  │
│  └────────────────────────┘                            │
└────────────────────────────────────────────────────────┘

---

Scenario A: Both Ollama and Open-WebUI in Docker Compose (Recommended)

If running both services via Docker Compose, use container service names for automatic DNS resolution within the shared bridge network.

Correct docker-compose.yml Specification

version: "3.8"

services:
  ollama:
    image: ollama/ollama:latest
    container_name: ollama_service
    restart: unless-stopped
    volumes:
      - ollama_storage:/root/.ollama
    ports:
      - "11434:11434"
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    networks:
      - ai_network

  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: open_webui
    restart: unless-stopped
    ports:
      - "3000:8080"
    environment:
      # CRITICAL FIX: Use container name 'ollama' instead of 'localhost'
      - OLLAMA_BASE_URL=http://ollama:11434
    volumes:
      - webui_storage:/app/backend/data
    depends_on:
      - ollama
    networks:
      - ai_network

networks:
  ai_network:
    driver: bridge

volumes:
  ollama_storage:
  webui_storage:

---

Scenario B: Open-WebUI in Docker, Ollama Native on Host

If Ollama is installed natively on your Linux host (outside Docker), the container must reach the host network interface.

Step 1: Bind Ollama to All Interfaces (0.0.0.0)

By default, native Ollama binds only to 127.0.0.1:11434. Modify the systemd service to accept incoming bridge connections:

Edit Ollama service config:

sudo systemctl edit ollama.service

Add the environment override block:

[Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"

Save, exit, and reload systemd:

sudo systemctl daemon-reload
sudo systemctl restart ollama

Verify port binding:

netstat -tulpn | grep 11434
# Output should show 0.0.0.0:11434 (NOT 127.0.0.1:11434)

Step 2: Use host.docker.internal in Open-WebUI Container

Launch Open-WebUI using host.docker.internal:

docker run -d -p 3000:8080   --add-host=host.docker.internal:host-gateway   -e OLLAMA_BASE_URL=http://host.docker.internal:11434   -v open-webui:/app/backend/data   --name open-webui   --restart unless-stopped   ghcr.io/open-webui/open-webui:main

---

Verification & Connection Testing

Test connectivity directly from within the open-webui container to confirm resolution:

docker exec -it open-webui curl http://ollama:11434/api/version

Expected Successful Output:

{"version":"0.1.38"}

---

Diagnostic Matrix & Troubleshooting

Error Message	Cause	Solution
Connection refused: localhost:11434	Open-WebUI attempting loopback inside container	Update OLLAMA_BASE_URL to http://ollama:11434 or http://host.docker.internal:11434.
502 Bad Gateway	Ollama container still starting or crashing	Check docker logs ollama_service for model load failures or GPU errors.
No models detected in WebUI dropdown	Ollama API reachable but no models pulled	Run docker exec -it ollama_service ollama pull llama3.
CORS Error in Browser Console	Ollama blocking frontend origins	Add Environment="OLLAMA_ORIGINS=*" to systemd service or Docker env.

---

Key Takeaways

1. Container Isolation: localhost inside a container never reaches external host services without --add-host or network bridge configuration.
2. Host Gateway: Use --add-host=host.docker.internal:host-gateway for host-native services.
3. Bridge DNS: Docker Compose automatically handles container name resolution when services share a defined bridge network.

Root Cause Analysis & Deep Diagnostics

┌────────────────────────────────────────────────────────────┐
│                DIAGNOSTIC WORKFLOW MATRIX                  │
│                                                            │
│  1. Check Kernel & Driver State (dmesg / nvidia-smi)       │
│  2. Inspect Container Runtime Logs (docker logs -f)        │
│  3. Verify Host Network Bindings (netstat / ss -tulpn)    │
│  4. Validate Environment Variables & Secret Tokens         │
└────────────────────────────────────────────────────────────┘

Diagnostic Command Sequence

Run the following diagnostic script to isolate kernel, container, and memory bottlenecks:

#!/usr/bin/env bash
set -euo pipefail

echo "=== System Kernel & Driver Status ==="
uname -r
nvidia-smi || echo "NVIDIA Driver missing or unloaded"

echo "=== Container Health & Port Allocation ==="
docker ps --format "table {{.Names}}	{{.Status}}	{{.Ports}}"

echo "=== Memory & Swap Diagnostics ==="
free -h
swapon --show

echo "=== Systemd Service Logs ==="
journalctl -u docker -n 50 --no-pager

Comprehensive Failure Modes & Solution Matrix

Error Code / Log Entry	Underlying Root Cause	Verification Command	Resolution Procedure
CUDA_ERROR_OUT_OF_MEMORY	Context window exceeds allocated VRAM	nvidia-smi	Enable 4-bit quantization (AWQ/GPTQ) or reduce --max-model-len.
docker: unknown option --gpus	Missing NVIDIA Container Toolkit hook	docker info | grep Runtime	Run sudo nvidia-ctk runtime configure and restart Docker.
502 Bad Gateway	Reverse proxy routed before backend ready	curl -Iv http://localhost:8000	Add container dependency healthchecks in docker-compose.yml.
Permission denied (publickey)	Incorrect SSH or token permission	ls -la ~/.ssh/	Fix file permissions: chmod 600 ~/.ssh/id_rsa.

---

Step-by-Step Verification Procedure

1. Verify Backend Availability: Ensure the backend container process is listening on the expected loopback interface using ss -tulpn | grep <port>.
2. Validate Payload Responses: Send a synthetic request payload using curl with verbose output -v to confirm HTTP 200 OK status.
3. Monitor System Telemetry: Watch memory and CPU counters in real time with htop or docker stats during peak request load.