Debugging Redis AsyncIO AttributeError in Docker

Introduction

I was containerizing a FastAPI backend with Docker Compose when I decided to waste my entire morning with this error:

1
AttributeError: '_AsyncHiredisParser' object has no attribute '_connected'

The application worked perfectly on my Windows development machine. Every test passed. Redis was fast. OAuth flow was smooth. Then I put it in a Docker container and watched it explode.

After an hour or two of debugging GitHub issues and suspecting library bugs, the real culprit turned out to be three innocent-looking numbers in my configuration: {1: 60, 2: 10, 3: 6}. Platform-specific TCP socket constants that mean different things on Windows and Linux. Who knew? (Everyone. Everyone knew. I just forgot.)

This is the story of how minimal reproduction tests saved an hour of my life, and how I should have been working on the frontend instead.

TL;DR

While containerizing a FastAPI backend, I encountered AttributeError: '_AsyncHiredisParser' object has no attribute '_connected' when using Redis AsyncIO. The root cause: hardcoded TCP keepalive socket option constants that were valid on Windows but invalid in the Linux Docker container.

The Fix: Remove platform-specific socket_keepalive_options and let Redis use system defaults.

The Setup

I had a FastAPI backend running on Windows, connecting to containerized infrastructure. The infrastructure (PostgreSQL, Redis, N8N) was already running in Docker Compose, but the FastAPI backend itself was still running locally with uvicorn app.main:app in my terminal.

The Architecture:

• Windows local: FastAPI backend (Python 3.12)
• Docker Compose: PostgreSQL, Redis, N8N

Tech Stack:

• FastAPI (Python 3.12)
• redis-py 7.0.1 with hiredis 3.3.0
• Docker Compose with Podman
• uv package manager

This hybrid setup worked perfectly. The Windows-based FastAPI connected to the Docker-based Redis without issues. OAuth flow was smooth. Everything was fast.

Then I decided to containerize the FastAPI backend too, to have everything in Docker Compose. Same code, same configuration, just running in a container instead of Windows.

That’s when Redis connections started failing. What could go wrong?

Issue #1: Dockerfile Build Failure - Missing README.md

Error:

1
OSError: Readme file does not exist: README.md

Root Cause: The project uses hatchling as the build backend, which requires README.md during dependency installation. Because apparently build tools need documentation to install code.

Initial Dockerfile:

1
COPY pyproject.toml uv.lock ./
2
RUN uv sync --no-dev

Fix:

1
COPY pyproject.toml uv.lock README.md ./
2
RUN uv sync --no-dev

✅ Build passed. Next problem.

Issue #2: uvicorn Not Found in PATH

Error:

1
crun: executable file 'uvicorn' not found in $PATH

Root Cause: uv sync creates a virtual environment (.venv), but the CMD tries to run uvicorn directly without activating the venv.

Attempted Solutions:

1. ❌ UV_SYSTEM_PYTHON=1 with uv sync - Still created .venv
2. ❌ uv run uvicorn - Required proper venv setup
3. ✅ System-wide installation with locked versions

Final Solution:

1
# Export locked dependencies to requirements.txt and install system-wide
2
RUN uv export --frozen --no-dev --no-hashes -o requirements.txt && \
3
    uv pip install --system --no-cache -r requirements.txt && \
4
    rm requirements.txt
5

6
# Direct uvicorn command (no uv run needed)
7
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

This approach:

• Maintains exact lockfile versions (--frozen)
• Installs system-wide without venv (--system)
• Allows direct uvicorn execution

✅ Container started. Logs looked good. Time to test the actual application.

And that’s when things got weird.

Issue #3: The Mystery - Redis AttributeError

I tried logging in via Google OAuth. The backend should have:

1. Generated a CSRF state token
2. Stored it in Redis with expiration
3. Redirected to Google’s OAuth page

Instead, I got this:

1
{
2
  "error": {
3
    "code": "INTERNAL_ERROR",
4
    "message": "Error: '_AsyncHiredisParser' object has no attribute '_connected'",
5
    "details": {
6
      "traceback": "...await redis.setex(state_key, settings.oauth_state_expiry, json.dumps(state_data))..."
7
    }
8
  }
9
}

The error was happening during redis.setex() - a basic Redis operation that should just work. And it did work on my Windows machine. But inside the Docker container? Complete failure.

Going Down the Rabbit Hole

When you see an error message like '_AsyncHiredisParser' object has no attribute '_connected', your brain immediately goes to library bugs. I spent way too long investigating:

• ❌ GitHub Issue #3745: There was a known bug with health_check_interval in redis-py. Added health check. Didn’t help.
• ❌ Version mismatch: Maybe Docker had different package versions? Nope, checked with pip list, everything matched.
• ❌ Network configuration: Maybe it’s a Docker network issue? But PostgreSQL worked fine, so probably not.

The error traceback pointed to deep inside redis-py’s hiredis parser:

1
File "/usr/local/lib/python3.12/site-packages/redis/_parsers/hiredis.py", line 240
2
    if not self._connected:
3
           ^^^^^^^^^^^^^^^
4
AttributeError: '_AsyncHiredisParser' object has no attribute '_connected'

This looked like _connected wasn’t being initialized. But why would that only happen in Docker?

I opened the redis-py source code to understand what was happening. The _AsyncHiredisParser class should initialize _connected in its on_connect() callback. If that attribute didn’t exist, it meant on_connect() never ran—which meant the connection never succeeded in the first place.

The Turning Point: Minimal Reproduction

After too much time reading GitHub issues and redis-py internals, I decided to take a step back. When debugging gets this confusing, there’s one strategy that never fails: isolate the problem.

I wrote the simplest possible Redis test:

1
import asyncio
2
from redis.asyncio import from_url
3

4
async def test_basic_connection():
5
    redis = from_url(
6
        "redis://redis:6379/0",
7
        encoding="utf-8",
8
        decode_responses=True,
9
        max_connections=10,
10
        socket_timeout=5,
11
    )
12

13
    await redis.setex("test_key", 10, "test_value")
14
    value = await redis.get("test_key")
15
    print(f"✓ GET successful: {value}")
16

17
    await redis.delete("test_key")
18
    await redis.close()
19

20
asyncio.run(test_basic_connection())

I ran this inside the Docker container, fully expecting it to fail with the same AttributeError.

It worked perfectly. ✅

This was the breakthrough. redis-py itself was fine. The problem wasn’t the library, the network, or the Docker environment. The problem was my configuration.

Finding the Real Culprit

If the minimal test passed but my application failed, the issue must be in how I was configuring Redis. I created another test, this time using my actual RedisClient class:

1
from app.redis_client import RedisClient
2

3
async def test_redis_client_class():
4
    client = RedisClient()
5
    await client.connect()
6
    await client.setex("test_key", 10, "test_value")
7
    # ...

This failed. ❌

But with a different error message that I’d been missing in the logs:

1
OSError: [Errno 22] Invalid argument
2
  at sock.setsockopt(socket.SOL_TCP, k, v)

There it was. The real error. setsockopt() was failing with “Invalid argument” during socket setup. And then the connection attempt would fail, leading to the AttributeError when trying to access _connected before it was initialized.

The Problematic Configuration

I looked at my Redis configuration:

1
redis_socket_keepalive_options: dict[int, int] = {
2
    1: 60,  # TCP_KEEPIDLE
3
    2: 10,  # TCP_KEEPINTVL
4
    3: 6,   # TCP_KEEPCNT
5
}

And suddenly it all made sense.

Understanding the Root Cause

Those numbers—1, 2, 3—aren’t universal constants. They’re platform-specific socket option constants that map to TCP keepalive parameters.

On Windows (where I developed), those values happen to correspond to:

• 1 = Some keepalive setting
• 2 = Another keepalive setting
• 3 = Yet another keepalive setting

On Linux (inside the Docker container), those same numbers mean completely different things, or worse, nothing at all. When Redis tried to call:

1
sock.setsockopt(socket.SOL_TCP, 1, 60)  # Invalid on Linux!

The Linux kernel responded with “Invalid argument” because 1 isn’t a valid TCP socket option constant on that platform.

The proper way to do this would be using the symbolic constants:

1
import socket
2

3
socket_keepalive_options = {
4
    socket.TCP_KEEPIDLE: 60,   # Symbolic constant, platform-aware
5
    socket.TCP_KEEPINTVL: 10,
6
    socket.TCP_KEEPCNT: 6,
7
}

These symbolic constants get translated to the correct numeric values for each platform at runtime.

But here’s the thing: I didn’t need these custom keepalive options at all. Redis already has sensible defaults, and the OS handles TCP keepalive just fine without me trying to be clever.

The Error Chain Explained

Now the full error sequence made sense:

1. Redis tries to establish connection with my custom socket_keepalive_options
2. setsockopt() fails with OSError: Invalid argument because the constants are platform-specific
3. Connection fails and enters retry logic
4. During retry, redis-py calls can_read_destructive() to check connection state
5. This tries to access self._connected attribute
6. But _connected is only initialized in the on_connect() callback
7. Since connection never succeeded, on_connect() never ran
8. AttributeError: '_AsyncHiredisParser' object has no attribute '_connected'

The AttributeError wasn’t the bug—it was a symptom of the earlier socket configuration failure.

The Fix

The solution was simple: remove the problematic configuration.

1
redis_socket_keepalive: bool = True
2
# Let Redis use system defaults for TCP keepalive
3
# Platform-specific constants cause "Invalid argument" errors in Docker
4
redis_socket_keepalive_options: dict[int, int] | None = None

1
async def connect(self) -> None:
2
    """Establish Redis connection."""
3
    if self._redis is None:
4
        conn_params = {
5
            "encoding": "utf-8",
6
            "decode_responses": True,
7
            "max_connections": settings.redis_max_connections,
8
            "socket_timeout": settings.redis_socket_timeout,
9
            "socket_connect_timeout": settings.redis_socket_connect_timeout,
10
            "socket_keepalive": settings.redis_socket_keepalive,
11
        }
12

13
        # Only add socket_keepalive_options if configured
14
        if settings.redis_socket_keepalive_options:
15
            conn_params["socket_keepalive_options"] = settings.redis_socket_keepalive_options
16

17
        self._redis = from_url(str(settings.redis_url), **conn_params)

Rebuilt the Docker image, restarted the containers, tested OAuth login.

It worked. ✅

Lessons Learned

1. Minimal reproduction tests are your best friend

When debugging complex issues, the first instinct is to dig deeper into the complex system. Sometimes the better approach is to step back and create the simplest possible test case. This immediately told me: “redis-py works fine, your config doesn’t.”

2. Error messages lie (or at least, they mislead)

The AttributeError looked like a redis-py bug. It even had a GitHub issue that seemed related. But the real error—OSError: Invalid argument—was hiding earlier in the logs, overshadowed by the more dramatic exception.

3. Platform-specific constants are dangerous

Hardcoded numeric values like {1: 60, 2: 10, 3: 6} might work on your development machine, but they’re time bombs waiting to explode in production. If you must use low-level socket options:

• Use symbolic constants (socket.TCP_KEEPIDLE, not 1)
• Or better yet, let the library use platform-appropriate defaults

4. Code that works locally can fail in production for subtle reasons

Windows and Linux aren’t just different operating systems—they have different kernels, different system libraries, and different constant mappings. “Works on my machine” is a meme for a reason.

5. Premature optimization is real

I added those socket keepalive options thinking I was optimizing Redis performance. I had no measurements. I had no specific problem I was solving. I was just cargo-culting configuration I’d seen somewhere else. And it broke my application in production.

Conclusion

What started as a mysterious AttributeError in Redis AsyncIO turned out to be a lesson in platform compatibility and the dangers of premature optimization. The fix was removing code, not adding it.

Now my FastAPI backend runs happily in Docker, OAuth works perfectly, and Redis does its job without me trying to micromanage its TCP socket behavior. The way it should be.

🐛🐛🐛🐛🐛🐛🐛🐛🐛🐛

References

• redis-py GitHub repository - Official redis-py source code
• redis-py hiredis parser source - The file where the error occurred
• redis-py GitHub Issue #3745 - Related async connection bug
• Python socket module documentation - TCP socket options
• TCP Keepalive HOWTO - Understanding TCP keepalive
• Docker and platform-specific issues - Cross-platform Docker builds