Fix OperationalError: kombu.exceptions.OperationalError: [Errno 111] Connection refused in Celery

This error occurs when a Celery worker or producer cannot connect to the message broker, usually Redis or RabbitMQ. The broker may not be running, the connection URL may be wrong, or a firewall is blocking the port. Fix it by verifying the broker is running, the CELERY_BROKER_URL is correct, and the broker port is accessible from your application.

Reading the Stack Trace

Here's what each line means:

• File "/app/venv/lib/python3.12/site-packages/kombu/connection.py", line 451, in ensure_connection: Kombu (Celery's messaging library) tries to establish a connection to the broker but fails after retries.
• File "/app/venv/lib/python3.12/site-packages/kombu/transport/pyamqp.py", line 201, in establish_connection: The AMQP transport layer attempts a TCP connection to the broker host and port.
• kombu.exceptions.OperationalError: [Errno 111] Connection refused: The operating system refused the TCP connection, meaning nothing is listening on the broker's port.

Common Causes

# docker-compose.yml missing redis service
services:
  web:
    build: .
  worker:
    command: celery -A app.celery worker
    # No redis service defined!

# config.py
CELERY_BROKER_URL = 'amqp://localhost:5672'  # RabbitMQ not on this host in Docker

# Docker services on different networks:
services:
  redis:
    networks: [backend]
  worker:
    networks: [frontend]  # cannot reach redis

The Fix

Ensure the broker service is running and the CELERY_BROKER_URL correctly references the broker's hostname and port. In Docker, use the service name (redis) as the hostname rather than localhost. Add depends_on to ensure the broker starts before the worker.

# config.py
CELERY_BROKER_URL = 'amqp://localhost:5672'

# config.py
import os
CELERY_BROKER_URL = os.environ.get('CELERY_BROKER_URL', 'redis://localhost:6379/0')

# docker-compose.yml
# services:
#   redis:
#     image: redis:7-alpine
#     ports:
#       - "6379:6379"
#   worker:
#     build: .
#     command: celery -A app.celery worker --loglevel=info
#     depends_on:
#       - redis
#     environment:
#       - CELERY_BROKER_URL=redis://redis:6379/0

Testing the Fix

import pytest
from unittest.mock import patch
from app import create_app
from app.tasks import add_numbers

@pytest.fixture
def app():
    app = create_app()
    app.config['TESTING'] = True
    app.config['CELERY_BROKER_URL'] = 'memory://'
    app.config['CELERY_RESULT_BACKEND'] = 'cache+memory://'
    return app

def test_celery_task_runs_eagerly(app):
    app.config['CELERY_ALWAYS_EAGER'] = True
    result = add_numbers.delay(2, 3)
    assert result.get() == 5

def test_broker_url_is_configured(app):
    assert app.config['CELERY_BROKER_URL'] is not None
    assert len(app.config['CELERY_BROKER_URL']) > 0

Run your tests:

pytest tests/ -v

Pushing Through CI/CD

git checkout -b fix/celery-broker-connection,git add config.py docker-compose.yml,git commit -m "fix: configure correct broker URL and add Redis service",git push origin fix/celery-broker-connection

Your CI config should look something like this:

name: CI
on:
  pull_request:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    services:
      redis:
        image: redis:7-alpine
        ports:
          - 6379:6379
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
          cache: 'pip'
      - run: pip install -r requirements.txt
      - run: pytest tests/ -v --tb=short
        env:
          CELERY_BROKER_URL: redis://localhost:6379/0

The Full Manual Process: 18 Steps

Here's every step you just went through to fix this one bug:

1. Notice the error alert or see it in your monitoring tool
2. Open the error dashboard and read the stack trace
3. Identify the file and line number from the stack trace
4. Open your IDE and navigate to the file
5. Read the surrounding code to understand context
6. Reproduce the error locally
7. Identify the root cause
8. Write the fix
9. Run the test suite locally
10. Fix any failing tests
11. Write new tests covering the edge case
12. Run the full test suite again
13. Create a new git branch
14. Commit and push your changes
15. Open a pull request
16. Wait for code review
17. Merge and deploy to production
18. Monitor production to confirm the error is resolved

Total time: 30-60 minutes. For one bug.

pip install bugstack

import bugstack

bugstack.init(api_key=os.environ["BUGSTACK_API_KEY"])

Deploying the Fix (Manual Path)

1. Verify the broker service is running and accessible.
2. Open a pull request with the broker configuration fix.
3. Wait for CI checks with Redis service to pass.
4. Have a teammate review and approve the PR.
5. Merge to main and verify the Celery worker connects to the broker in staging.

Frequently Asked Questions