Startup crash in FastMCP HTTP app due to fakeredis aioredis import mismatch (FakeServer/FakeConnection)

[iowathe3rd]

What happened?

Summary

FastMCP HTTP server fails during ASGI lifespan startup (before any tool execution) due to import errors in Docket Redis memory backend:

• ImportError: cannot import name 'FakeConnection' from 'fakeredis.aioredis'
• ImportError: cannot import name 'FakeServer' from 'fakeredis.aioredis'

This is a hard startup failure: server process exits, MCP tools are never available.

---

Minimal reproducible example

from fastmcp import FastMCP

mcp = FastMCP("ReproServer", stateless_http=True)
app = mcp.http_app()

Run:

python -m uvicorn app:app --host 0.0.0.0 --port 8000

---

Actual behavior

Startup fails in lifespan.

Observed traceback path:

• fastmcp.server.server._docket_lifespan
• docket._redis._memory_connection_pool
• from fakeredis.aioredis import FakeConnection, FakeServer

Observed errors:

ImportError: cannot import name 'FakeConnection' from 'fakeredis.aioredis'

ImportError: cannot import name 'FakeServer' from 'fakeredis.aioredis'

---

Expected behavior

Server should start successfully:

INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000

---

Environment

• Date: 2026-04-12
• Python: 3.11
• FastMCP: 2.14.3
• Uvicorn: 0.35.*
• Dependency manager: Poetry
• App mode: mcp.http_app()

Note: warning about stateless_http deprecation is present, but it is not the crash cause.

---

Workaround (used and validated)

1) Pin fakeredis

In pyproject.toml:

fakeredis = "2.32.1"

2) Re-lock and install

poetry lock
poetry install

3) Validate required symbols

poetry run python -c "from fakeredis.aioredis import FakeConnection, FakeServer; print('fakeredis OK')"

Expected:

fakeredis OK

4) Re-run server

poetry run python -m uvicorn app.server:app --host 0.0.0.0 --port 8000

Result after workaround: startup succeeds.

---

Why this matters

• Failure happens before any app/tool logic.
• Error surfaces from transitive dependency internals, hard to diagnose quickly.
• Behavior may vary by environment/dependency drift.

---

Additional context

In our incident, environment drift (manual package changes) made dependency state inconsistent with expected compatibility window, which triggered this startup failure.

---

Suggested improvement

A clearer compatibility guard would help users, e.g.:

• tighter constraints in dependency chain for fakeredis compatibility,
• and/or a startup-time remediation hint when incompatible symbols are missing.

Example Code

Version Information

FastMCP version:                                                         2.14.3
MCP version:                                                             1.27.0
Python version:                                                          3.11.0
Platform:          Linux-6.6.87.2-microsoft-standard-WSL2-x86_64-with-glibc2.39
FastMCP root path:      /home/u19203/dev/mcp/.venv/lib/python3.11/site-packages

[iowathe3rd]

cunla/fakeredis-py#419

[vincent067]

Hey @iowathe3rd, thanks for the detailed report! 👋

I just dug into this and I think I know what's going on. The crash you're seeing is caused by fakeredis 2.35.0 renaming/moving FakeConnection and FakeServer in fakeredis.aioredis, which breaks pydocket's memory backend. This isn't really a FastMCP bug per se — it's a transitive dependency mismatch.

Here's the timeline I found in the repo:

• Pin fakeredis<2.35.0 in tasks extra #3804 (Apr 9) — fakeredis was temporarily pinned to <2.35.0 on main
• Bump pydocket>=0.19.0, drop fakeredis pin #3822 (Apr 10) — pydocket was bumped to 0.19.0 on main, which apparently fixes the FakeConnection rename internally, so the pin was dropped

The catch is that you're running FastMCP 2.14.3, which is on the release/2.x branch. Looking at the 2.x branch, it still depends on pydocket>=0.17.2 and doesn't have either fix yet. So 2.x users are getting hit by this when their environment resolves to fakeredis 2.35.0.

Your workaround is spot-on — pinning fakeredis==2.32.1 is the safest immediate fix for anyone on 2.14.x. 😊

For the maintainers: I think release/2.x needs either:

1. A backport of the pydocket>=0.19.0 bump (if it's compatible with 2.x), or
2. A direct fakeredis<2.35.0 constraint added to the core deps on release/2.x

I'm happy to open a PR for option 2 if that's the preferred short-term fix — just let me know!

Hope this helps clarify the root cause. 🙏

[vincent067]

Hey again! 👋 I just opened #3883 to add the direct fakeredis<2.35.0 cap on the release/2.x branch.

This should prevent the startup crash for anyone on the current 2.14.x releases while the team decides whether to also backport the pydocket bump from main.

Feel free to take it for a spin if you're building from source — otherwise hopefully it'll land in the next 2.14 patch release. 😊 Let me know if anything looks off!

[jlowin]

Closed in #3883 and released in 2.14.7