Fix ConnectionError: Error 111 connecting to localhost:6379. Connection refused. in Django

This error means Django cannot connect to the configured cache backend, usually Redis or Memcached. Fix it by verifying the cache server is running, checking the connection settings in CACHES, ensuring the correct host and port are configured, and adding a fallback to LocMemCache for development environments.

Reading the Stack Trace

Here's what each line means:

• File "/app/products/views.py", line 14, in product_list: The view tries to read from the cache before hitting the database, but the cache connection fails.
• File "/venv/lib/python3.11/site-packages/django_redis/cache.py", line 88, in get: django-redis attempts to connect to Redis to retrieve the cached value.
• redis.exceptions.ConnectionError: Error 111 connecting to localhost:6379. Connection refused.: Redis is not running on localhost:6379, or a firewall is blocking the connection.

Common Causes

# settings.py
CACHES = {
    'default': {
        'BACKEND': 'django_redis.cache.RedisCache',
        'LOCATION': 'redis://localhost:6379/0',
    }
}
# Redis not started: sudo systemctl start redis

# settings.py — same config used in production
CACHES = {
    'default': {
        'BACKEND': 'django_redis.cache.RedisCache',
        'LOCATION': 'redis://localhost:6379/0',  # Should be redis://redis-host:6379/0
    }
}

# No fallback configured — cache failures crash the entire site
CACHES = {
    'default': {
        'BACKEND': 'django_redis.cache.RedisCache',
        'LOCATION': 'redis://localhost:6379/0',
    }
}

The Fix

Read the Redis URL from an environment variable so production can point to the correct host. Enable IGNORE_EXCEPTIONS so cache failures return None instead of crashing. Add timeouts to prevent slow connections from blocking requests. Provide a LocMemCache fallback for development.

# settings.py
CACHES = {
    'default': {
        'BACKEND': 'django_redis.cache.RedisCache',
        'LOCATION': 'redis://localhost:6379/0',
    }
}

import os

# settings.py
CACHES = {
    'default': {
        'BACKEND': 'django_redis.cache.RedisCache',
        'LOCATION': os.environ.get('REDIS_URL', 'redis://localhost:6379/0'),
        'OPTIONS': {
            'CLIENT_CLASS': 'django_redis.client.DefaultClient',
            'IGNORE_EXCEPTIONS': True,  # Gracefully handle Redis downtime
            'SOCKET_CONNECT_TIMEOUT': 5,
            'SOCKET_TIMEOUT': 5,
        },
    }
}

# For development without Redis:
if os.environ.get('USE_LOCMEM_CACHE'):
    CACHES = {
        'default': {
            'BACKEND': 'django.core.cache.backends.locmem.LocMemCache',
        }
    }

Testing the Fix

import pytest
from unittest.mock import patch
from django.test import TestCase, Client
from django.core.cache import cache


class TestCacheBackend(TestCase):
    def test_cache_set_and_get(self):
        cache.set('test_key', 'test_value', timeout=60)
        assert cache.get('test_key') == 'test_value'

    def test_cache_miss_returns_none(self):
        assert cache.get('nonexistent_key') is None

    def test_view_works_without_cache(self):
        """View should work even if cache is unavailable."""
        with patch.object(cache, 'get', return_value=None):
            client = Client()
            response = client.get('/products/')
            assert response.status_code == 200

    def test_cache_delete(self):
        cache.set('delete_me', 'value', timeout=60)
        cache.delete('delete_me')
        assert cache.get('delete_me') is None

Run your tests:

pytest

Pushing Through CI/CD

git checkout -b fix/redis-cache-connection,git add settings.py,git commit -m "fix: add Redis connection resilience and env-based cache config",git push origin fix/redis-cache-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
        ports:
          - 6379:6379
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
          cache: 'pip'
      - run: pip install -r requirements.txt
      - run: pytest --tb=short -q
        env:
          REDIS_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. Run the full test suite locally to confirm cache operations work.
2. Open a pull request with the cache configuration changes.
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 cache connectivity in staging.

Frequently Asked Questions