Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

Python requests fails with Errno 111 Connection refused between Compose services

ErrorMax retries exceeded with url

Short answer

Errno 111 means nothing accepted the connection at that address. Between Compose services the usual reasons are calling localhost or the published host port instead of the service name and container port, a server bound to 127.0.0.1 inside its container, or a caller that starts before the server is ready.

  • Applies to Docker Compose v2, Python 3.13, Django 5.2
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    From inside the calling container, try the exact URL your code uses. If it fails there too, the URL or the target is wrong, not requests.

    docker compose exec web python -c "import urllib.request as u; print(u.urlopen('http://api:8000/').status)"
  2. 2Match what you see, then jump to its fix

    1. 1The URL is http://localhost:PORT or names the left-hand number of a HOST:CONTAINER port mappingThe URL uses localhost or the published host portFix
    2. 2The service answers from inside its own container but refuses other containersThe server listens only on 127.0.0.1 inside its own containerFix
    3. 3The error appears at startup and goes away if you restart the caller laterThe caller started before the server was readyFix

What does the error look like?

  • Max retries exceeded with url
  • Failed to establish a new connection: [Errno 111] Connection refused

Cause 1 of 3

The URL uses localhost or the published host port

1Check

Containers on one Compose network reach each other by service name, and traffic between them uses the container port, the right-hand number. The host port only matters from outside the network.

grep -n -B2 -A4 "ports:" docker-compose.yml
grep -R -n "http://localhost" --include=*.py .

2Fix

Call the service name and the container port. Keep the value in an environment variable.

# docker-compose.yml: api publishes "8001:8000"
# inside the web container, use the service name and port 8000
API_URL=http://api:8000

3Verify

Run the request again from the calling container.

docker compose exec web python -c "import os, requests; print(requests.get(os.environ['API_URL']).status_code)"

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 3

The server listens only on 127.0.0.1 inside its own container

1Check

Django runserver binds 127.0.0.1:8000 unless told otherwise, and so does Gunicorn. 127.0.0.1 in a container is that container only. Other containers cannot reach it.

docker compose exec api sh -c 'ss -ltn || netstat -ltn'

2Fix

Bind to all interfaces in the container.

python manage.py runserver 0.0.0.0:8000
# or, with Gunicorn
gunicorn --bind 0.0.0.0:8000 myproject.wsgi:application

3Verify

Repeat the request from the other container.

docker compose exec web python -c "import requests; print(requests.get('http://api:8000/').status_code)"

Confirmed by docs.djangoproject.com

Did this fix it?

Cause 3 of 3

The caller started before the server was ready

1Check

Compose starts services in dependency order, but a container being started is not the same as a server accepting connections. Without a health check, depends_on cannot wait for readiness.

docker compose ps

2Fix

Add a health check to the server and make the caller wait for it to be healthy.

services:
  web:
    build: .
    depends_on:
      api:
        condition: service_healthy
  api:
    build: ./api
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request as u; u.urlopen('http://localhost:8000/')"]
      interval: 10s
      retries: 5
      start_period: 30s

3Verify

Bring the stack up from scratch and watch web start after api is healthy.

docker compose down && docker compose up

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Put service URLs in environment variables and use the Compose service name in them.
  • Always bind servers in containers to 0.0.0.0.
  • Add a health check to every service other services depend on.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.