tiangolo/fastapi · error · HTTPException

Item not found

Error message

Item not found

What it means

FastAPI returns HTTP 404 with detail "Item not found" when the path parameter `item_id` is not a key in the in-memory `data` dict. The check `if item_id not in data` runs before the owner comparison, so unknown resources never reach the authorization logic. It is the canonical FastAPI pattern for missing-resource responses.

Source

Thrown at docs_src/dependencies/tutorial008b_py310.py:26

    "portal-gun": {"description": "Gun to create portals", "owner": "Rick"},
}


class OwnerError(Exception):
    pass


def get_username():
    try:
        yield "Rick"
    except OwnerError as e:
        raise HTTPException(status_code=400, detail=f"Owner error: {e}")


@app.get("/items/{item_id}")
def get_item(item_id: str, username: str = Depends(get_username)):
    if item_id not in data:
        raise HTTPException(status_code=404, detail="Item not found")
    item = data[item_id]
    if item["owner"] != username:
        raise OwnerError(username)
    return item

View on GitHub (pinned to 42a41db11f)

Solutions

1. Request a known item_id present in `data` ("plumbus" or "portal-gun").
2. If wiring a real store, replace the dict membership test with a DB lookup and keep the same 404 on miss.
3. Log the missing id server-side for telemetry while returning the generic 404 to the client.
4. Add a route-level test covering the not-found case.

Example fix

# before
if item_id not in data:
    raise HTTPException(status_code=404, detail="Item not found")

# after (DB-backed)
item = session.get(Item, item_id)
if item is None:
    raise HTTPException(status_code=404, detail="Item not found")

KNOWN_ITEMS = {"plumbus", "portal-gun"}
if item_id not in KNOWN_ITEMS:
    raise KeyError(f"unknown item {item_id}; valid: {KNOWN_ITEMS}")
client.get(f"/items/{item_id}")

def item_exists(item_id: str, store: dict) -> bool:
    return item_id in store

r = client.get(f"/items/{item_id}")
if r.status_code == 404 and r.json().get("detail") == "Item not found":
    # offer the user the list of valid ids
    ...

When it happens

Trigger: GET /items/{item_id} with an item_id that is neither "plumbus" nor "portal-gun" (e.g. /items/schmeckel).

Common situations: Client typos in resource ids; stale references to deleted records; switching from the toy dict to a real DB without preserving the existence check; returning 404 from a dependency that runs after other side effects.

Related errors

• Item not found, there's only a plumbus here
• Item not found, there's only a plumbus here
• Item not found, there's only a plumbus here
• Item not found, there's only a plumbus here
• Item not found

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