fastapi openapi utils.py UserWarning: Duplicate Operation ID for function #56

Activity

1. ctengel

   modified the milestones: Replication, Bug Fixes & Short-term on May 21, 2026
2. ctengel commented on May 22, 2026

   

   ctengel

   on May 22, 2026

   OwnerAuthor

   More actions

   Status: deferred — upstream FastAPI bug

   The warnings come from FastAPI's generate_unique_id() not distinguishing between methods when multiple are combined in a single api_route call. Both object_server.py and locator_api.py use @app.api_route("/{bucket}/{key}", methods=['GET', 'HEAD']), which triggers:

   UserWarning: Duplicate Operation ID get_object__bucket___key__head for function get_object
   UserWarning: Duplicate Operation ID find_object__bucket___key__head for function find_object
   

   Option A — Wait for an upstream FastAPI fix

   Tracked in FastAPI issues #4740 and #13175. Fix attempts:

   • PR #4851 — declined; maintainers consider multi-method api_route unsupported
   • PR #10694 — stale with merge conflicts
   • PR #15398 — open as of 2026-04-21, not yet merged

   All released versions through 0.136.1 still emit the warning; upgrading alone won't help.

   Option B — Fix on our end

   Replace the combined api_route with stacked decorators and explicit operation_id values matching openapi.yaml:

   # Before (object_server.py line 119, locator_api.py line 51):
   @app.api_route("/{bucket}/{key}", methods=['GET', 'HEAD'])
   
   # After:
   @app.get("/{bucket}/{key}", operation_id="getObject")
   @app.head("/{bucket}/{key}", operation_id="headObject")

   No function body changes needed. FileResponse and RedirectResponse already strip the body for HEAD responses via Starlette. Warnings disappear and operation IDs align with the hand-maintained spec.

   Decision: defer and watch FastAPI #15398. Revisit if it merges or if warnings start blocking tests.
3. ctengel

   modified the milestones: Bug Fixes & Short-term, Future on May 23, 2026
4. ctengel

   added

   bugSomething isn't workingSomething isn't working

   help wantedExtra attention is neededExtra attention is needed

   on May 28, 2026