tiangolo/fastapi · error · HTTPException

Item not found

Error message

Item not found

What it means

Raised by GET /items/{item_id} in the bigger-applications items router when item_id is not a key in fake_items_db (only "plumbus" and "gun" exist), returning HTTP 404. The router also declares responses={404} so the 404 is documented in the OpenAPI schema.

Source

Thrown at docs_src/bigger_applications/app_an_py310/routers/items.py:24

    prefix="/items",
    tags=["items"],
    dependencies=[Depends(get_token_header)],
    responses={404: {"description": "Not found"}},
)


fake_items_db = {"plumbus": {"name": "Plumbus"}, "gun": {"name": "Portal Gun"}}


@router.get("/")
async def read_items():
    return fake_items_db


@router.get("/{item_id}")
async def read_item(item_id: str):
    if item_id not in fake_items_db:
        raise HTTPException(status_code=404, detail="Item not found")
    return {"name": fake_items_db[item_id]["name"], "item_id": item_id}


@router.put(
    "/{item_id}",
    tags=["custom"],
    responses={403: {"description": "Operation forbidden"}},
)
async def update_item(item_id: str):
    if item_id != "plumbus":
        raise HTTPException(
            status_code=403, detail="You can only update the item: plumbus"
        )
    return {"item_id": item_id, "name": "The great Plumbus"}

View on GitHub (pinned to 42a41db11f)

Solutions

  1. Use a seeded id ("plumbus" or "gun").
  2. Handle 404 in the client with a fallback.
  3. List items via GET /items/ first to discover valid ids.

Example fix

# before
client.get("/items/xyz", headers=auth)
# after
client.get("/items/plumbus", headers=auth)
Defensive patterns

Strategy: validation

Validate before calling

valid_ids = {"plumbus", "gun"}
if item_id in valid_ids:
    client.get(f"/items/{item_id}", headers=auth)

Type guard

def item_exists(item_id: str, known: set[str]) -> bool:
    return item_id in known

Try / catch

resp = client.get(f"/items/{item_id}", headers=auth)
if resp.status_code == 404:
    ...

Prevention

When it happens

Trigger: GET /items/{item_id} with an id other than "plumbus" or "gun" (e.g. /items/xyz), after the X-Token check passes.

Common situations: Requesting an item id that was never seeded; typo; using an id from another dataset.

Related errors

AI-assisted analysis of tiangolo/fastapi@42a41db11f (2026-08-04). Data as JSON: /data/errors/f399096faee9061c.json. Report an issue: GitHub.