Summary

Litestar v3 is at 3.0.0b0 (beta) with no release date. We're on v2.21.1 (latest stable, March 2026). This issue tracks what to check when v3.0.0 stable ships.

Current Status (March 2026)

• Our version: litestar[standard,structlog,pydantic,brotli,prometheus]==2.21.1
• Latest stable: v2.21.1 (2026-03-07)
• v3 beta: 3.0.0b0 (on main branch)
• v3 milestone: 54% complete (6/11 issues closed), no due date
• Migration guide: Not written yet (TODO in roadmap)

Known v3 Breaking Changes (for our codebase)

High Impact

• AbstractAuthenticationMiddleware rework -- Our ApiAuthMiddleware (api/auth/middleware.py) inherits this. v3 is moving built-in middlewares to new ASGIMiddleware base class. Will need rewrite of create_auth_middleware_class().
• Implicit Optional removal -- v3 removes implicit None defaults for Optional handler params. Audit all controller handlers for explicit defaults.

Medium Impact

• Route handler config overhaul -- May affect how we register controllers and guards on Routers.
• Plugin protocols -> ABCs -- Deprecation of protocol-based plugin interface. We don't define custom plugins but may need import changes.
• RateLimitConfig middleware -- Base class changing; our rate limit setup in _build_middleware() may need updates.

Low Impact / Positive

• Pydantic v1 compat layer likely dropped -- Fixes our UserWarning: Core Pydantic V1 functionality isn't compatible with Python 3.14 warning (from litestar.plugins.pydantic.utils).
• __future__.annotations removal -- Aligns with our Python 3.14 / PEP 649 convention.
• OpenAPIController -> plugins -- We already use ScalarRenderPlugin, so this is a no-op for us.

No Impact

• ChannelsPlugin + WebSocket handler -- No changes mentioned
• CORSConfig, CompressionConfig -- No changes mentioned
• structlog integration -- No changes mentioned

Python 3.14 Support

v3 main branch declares >=3.9,<4.0 with classifiers up to 3.13 only. No 3.14 classifier yet. Likely works (we run 3.14 on v2.21.1 with only the pydantic v1 warning), but untested by Litestar CI.

Upgrade Triggers

Do NOT upgrade until ALL of these are true:

• v3.0.0 stable released (not beta)
• Migration guide published
• Python 3.14 in their test matrix or confirmed working

When Ready to Upgrade

1. Read migration guide
2. Check AbstractAuthenticationMiddleware replacement
3. Audit all handlers for implicit Optional params
4. Run full test suite against v3
5. Test WebSocket auth flow (may fix bug: WebSocket connections rejected with 403 despite correct auth exclude path #549)
6. Update pyproject.toml pin

References

• v3 Roadmap (issue #4009)
• v3 Milestone
• Litestar Releases