Skip to main content

Solved: 'dial tcp 127.0.0.1:11434: connect: connection refused' in Ollama

 You have successfully installed Ollama. You can verify it works by running ollama run llama3 in your terminal. You then spin up a UI like Open WebUI or a custom Docker container to interact with your models, but the connection fails immediately.

The logs display a fatal networking error: dial tcp 127.0.0.1:11434: connect: connection refused.

This guide resolves this specific networking blockage. It addresses the root cause of Docker interface isolation and Ollama's default binding security policies.

The Root Cause: Loopback Isolation

To fix this, you must understand why localhost is failing.

When you run a command inside a Docker container, localhost (or 127.0.0.1) refers to the container itself, not your host machine (your laptop or server).

If Ollama is running on your host OS (Mac, Windows, or Linux) and your application is running inside a Docker container, the application is trying to find Ollama inside the container’s network namespace. Since Ollama isn't installed inside that specific container, the connection is refused.

Furthermore, by default, Ollama binds specifically to 127.0.0.1. This is a security feature. It means Ollama refuses to listen to any request that does not originate from the loopback interface of the machine it is running on. Even if you bridge the networks, Ollama will reject external Docker traffic unless reconfigured.

Solution 1: Ollama on Host, App in Docker

This is the most common setup: you run Ollama natively for GPU access, and you run a tool like Open WebUI in Docker.

Step 1: Configure Ollama to Listen on All Interfaces

You must tell Ollama to stop listening only on localhost and start listening on 0.0.0.0 (all network interfaces).

For Linux (Systemd): If you installed Ollama via the install script, it runs as a systemd service. You need to override the environment variables.

Run the following command to open the override editor:

sudo systemctl edit ollama.service

In the editor, add the following lines within the [Service] block:

[Service]
Environment="OLLAMA_HOST=0.0.0.0"

Save and exit (Ctrl+O, Enter, Ctrl+X), then reload the daemon and restart Ollama:

sudo systemctl daemon-reload
sudo systemctl restart ollama

For macOS / Windows: If you are running the desktop application, you need to set the environment variable in your shell profile or the app launch configuration.

For macOS, run this in your terminal:

launchctl setenv OLLAMA_HOST "0.0.0.0"
# You must restart the Ollama application from the menu bar for this to take effect.

Step 2: Connect via the Host Gateway

Now that Ollama is listening, your Docker container needs the correct address to reach the host. Do not use 127.0.0.1.

For Docker Compose: Update your docker-compose.yml to use host-gateway. This maps host.docker.internal to your actual host machine's IP address.

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: open-webui
    restart: always
    ports:
      - "3000:8080"
    extra_hosts:
      - "host.docker.internal:host-gateway" # Maps host address
    environment:
      - OLLAMA_BASE_URL=http://host.docker.internal:11434
    volumes:
      - open-webui-data:/app/backend/data

volumes:
  open-webui-data:

If you are running a standard docker run command, add the flag --add-host=host.docker.internal:host-gateway.

Solution 2: The Full Docker Stack

If you prefer to run both Ollama and your UI inside Docker containers, you avoid the host-gateway complexity, but you must ensure they share a network.

This approach requires the NVIDIA Container Toolkit if you want GPU acceleration for Ollama inside Docker.

The Complete Docker Compose File

Create a file named docker-compose.yml. This creates a private internal network where the containers can resolve each other by service name.

name: llm-stack

services:
  # Service 1: The Model Runner
  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    restart: always
    tty: true
    ports:
      - "11434:11434"
    volumes:
      - ollama_storage:/root/.ollama
    # Enable GPU support (requires NVIDIA Container Toolkit)
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
    networks:
      - llm-network

  # Service 2: The UI
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: open-webui
    restart: always
    ports:
      - "3000:8080"
    environment:
      # Note: We use the service name 'ollama' here, not localhost
      - OLLAMA_BASE_URL=http://ollama:11434
    volumes:
      - open-webui-data:/app/backend/data
    depends_on:
      - ollama
    networks:
      - llm-network

volumes:
  ollama_storage:
  open-webui-data:

networks:
  llm-network:
    driver: bridge

Why This Works

  1. Service Discovery: By defining networks: - llm-network, Docker creates an internal DNS. The WebUI container can ping ollama by name.
  2. http://ollama:11434: In the environment variable, we replace localhost with the service name defined in the YAML file.
  3. Port Mapping: We still expose port 11434 to the host so you can access the API for debugging, but the internal communication happens over the bridge network.

Deep Dive: 0.0.0.0 vs 127.0.0.1

Understanding the difference between these IP addresses is critical for backend engineering.

  • 127.0.0.1 (Loopback): This is a private line. When a service binds here, it is saying, "I will only talk to processes running on the exact same kernel/OS instance as me." Since Docker containers have their own isolated network namespace, they are technically "different machines" regarding network logic.
  • 0.0.0.0 (All Interfaces): This is a wildcard. It tells the application to bind to every network card available (Ethernet, Wi-Fi, and the virtual Docker bridge docker0).

By setting OLLAMA_HOST=0.0.0.0, you allow the request coming from the Docker container (which travels over the docker0 bridge interface) to be accepted by the Ollama process.

Common Pitfalls and Edge Cases

1. Linux Firewall (UFW/Firewalld)

Even if you bind to 0.0.0.0, your Linux firewall might drop the packet. Docker usually modifies iptables automatically, but if you have a strict UFW setup, you may need to allow traffic on port 11434 from the Docker subnet.

# Allow traffic from default Docker bridge subnet
sudo ufw allow from 172.17.0.0/16 to any port 11434

2. Windows/Mac "host.docker.internal" magic

On Docker Desktop for Windows and Mac, host.docker.internal works out of the box because of internal DNS magic managed by the VM.

On Linux, this DNS name does not exist by default. This is why the extra_hosts section in the Docker Compose example above is mandatory for Linux users. It manually injects the entry into the container's /etc/hosts file.

3. Browser vs. Container Connectivity

A common point of confusion is: "I can open http://localhost:11434 in my Chrome browser, so why can't the container see it?"

  • Browser: Running on the Host. Can see Host localhost.
  • Container: Running in a virtual namespace. Cannot see Host localhost.

If the browser works, the Ollama service is running. If the container fails, it is strictly a networking configuration issue, not a service failure.

Conclusion

The connection refused error is rarely a bug in Ollama itself; it is a mismatch between Docker network isolation and application binding configuration.

By setting OLLAMA_HOST=0.0.0.0 and correctly mapping the host gateway or using a unified Docker network, you ensure your LLM stack communicates reliably. Always prefer the Docker Compose approach for reproducibility in production environments.

Labels: