Incompatibility with FastAPI 0.137+ / Starlette 1.3.1+

[erikmeier-8451]

Describe the bug

VersionedFastAPI crashes with AttributeError: '_IncludedRouter' object has no attribute 'endpoint' when used with FastAPI 0.137 (which depends on Starlette 1.3.1+).

In recent versions of Starlette, app.routes can contain _IncludedRouter objects in addition to the usual APIRoute instances. These _IncludedRouter objects are produced when include_router() is called and do not expose an .endpoint attribute. However, fastapi_versioning.versioning.version_to_route unconditionally accesses api_route.endpoint, leading to a hard failure during application startup.

Relevant traceback:

File ".../fastapi_versioning/versioning.py", line 44, in VersionedFastAPI
    version_to_route(route, default_version) for route in app.routes
File ".../fastapi_versioning/versioning.py", line 24, in version_to_route
    version = getattr(api_route.endpoint, "_api_version", default_version)
                      ^^^^^^^^^^^^^^^^^^
AttributeError: '_IncludedRouter' object has no attribute 'endpoint'

To Reproduce

Steps to reproduce the behavior:

1. Install fastapi==0.137.* (or any version pulling Starlette 1.3.1+) and fastapi-versioning==0.10.0.
2. Create a FastAPI app and register one or more sub-routers using app.include_router(...).
3. Wrap the application with VersionedFastAPI:

   from fastapi import APIRouter, FastAPI
   from fastapi_versioning import VersionedFastAPI, version
   
   router = APIRouter()
   
   @router.get("/hello")
   @version(1)
   def hello():
       return {"hello": "world"}
   
   base_app = FastAPI()
   base_app.include_router(router)
   
   versioned_app = VersionedFastAPI(
       base_app,
       version_format="{major}",
       prefix_format="/api/v{major}",
   )

4. Run the app (or import the module). The AttributeError is raised at import/startup time.

Expected behavior

VersionedFastAPI should iterate over app.routes and gracefully handle route entries that are not APIRoute instances (e.g., _IncludedRouter, Mount, WebSocketRoute, etc.), either by:

• Skipping non-APIRoute entries, or
• Recursing into included routers to discover the actual APIRoute objects they contain, or
• Preserving them unchanged in the resulting versioned application.

Application startup should succeed when using include_router() together with VersionedFastAPI on modern FastAPI/Starlette versions.

Additional context

• fastapi-versioning: 0.10.0
• fastapi: 0.137.x
• starlette: 1.3.1+
• Python: 3.12

Workaround

As a temporary workaround, filter out non-endpoint route objects from app.router.routes before passing the app to VersionedFastAPI. Note that this drops the routes added via include_router(), so it is only viable if those routes are added directly via decorators or re-registered after wrapping:

# fastapi-versioning 0.10.0 requires every route to have .endpoint;
# starlette 1.3.1+ adds _IncludedRouter objects that don't.
base_app.router.routes = [
    r for r in base_app.router.routes if hasattr(r, "endpoint")
]

versioned_app = VersionedFastAPI(
    base_app,
    version_format="{major}",
    prefix_format="/api/v{major}",
)

A proper fix in version_to_route (or its caller in VersionedFastAPI) is needed to restore compatibility with current FastAPI releases.

[mat81black]

Hi,

I ran into the same class of compatibility issues while working with API versioning on newer FastAPI/Starlette versions.

Since there haven’t been recent releases here, I’m sharing this in case it helps anyone who is blocked by this issue and is considering a migration path.

I maintain an alternative package:

https://github.com/mat81black/fastapi-router-versioning

Disclaimer: I am the author. Although the public repository/package is new, I have been using this approach in my own projects for about a year.

The main difference is that it versions routes from APIRouter instances instead of wrapping the whole FastAPI application. The goal is to keep the main app instance untouched, including middleware, lifespan, CORS and other global configuration.

It is not intended as an official fix for this repository, and it is not a drop-in replacement. I am only sharing it as an alternative for projects that are already evaluating a migration.

Compatibility note: the package supports FastAPI >=0.120.0, excluding only 0.137.0 and 0.137.1. I intentionally skipped those two intermediate releases because 0.137.0 changed FastAPI’s internal route structure, while 0.137.2 introduced iter_route_contexts() for advanced use cases that previously depended on router.routes. I preferred not to add special-case code for those two transitional versions.

I hope this helps someone landing here. Feel free to hide/remove this comment if third-party alternatives are out of scope for this issue.