"Value error, Expected UploadFile, received: <class 'str'>" When uploading file without filename.

[4c0n]

First Check

• I added a very descriptive title here.
• I used the GitHub search to find a similar question and didn't find it.
• I searched the FastAPI documentation, with the integrated search.
• I already searched in Google "How to X in FastAPI" and didn't find any information.
• I already read and followed all the tutorial in the docs and didn't find an answer.
• I already checked if it is not related to FastAPI but to Pydantic.
• I already checked if it is not related to FastAPI but to Swagger UI.
• I already checked if it is not related to FastAPI but to ReDoc.

Commit to Help

• I commit to help with one of those options 👆

Example Code

from fastapi import FastAPI

app = FastAPI()


@app.post("/upload")
def upload(file: UploadFile):
    return {"file", file.filename}

Description

When we use httpx to upload a file without a filename, FastAPI seems to give a unexpected response.
Now I realize that this is not a very common case, however it is possible and correct to upload a file omitting the name in the multipart form post request.

To reproduce consider the following code:

import httpx


async def test_upload() -> None:
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "http://localhost:8000/upload",
            files={"file": (None, open("test_file.txt", "rb")},
            headers={"Content-Type": "multipart/form-data; boundary=----FILEDATA"},
        )
        print(response.text)

Unfortunately this results in the 422 response:

{"detail":[{"type":"value_error","loc":["body","file"],"msg":"Value error, Expected UploadFile, received: <class 'str'>","input":"Hello World!","ctx":{"error":{}},"url":"https://errors.pydantic.dev/2.8/v/value_error"}]}

Where one would expect a 200 response with body:

{"file": null}

as the filename property of UploadFile is None by default.

Please correct me if I am wrong, but it seems like an edge case that FastAPI currently does not support.
It is a bit annoying, because in order to satisfy mypy we have to check that the filename is not None if we want to use it in our code, however we cannot currently test the case where it actually is None, because the input validation fails in a odd way.

Not sure where to look when it comes to fixing this, but I would be willing to spend some time debugging this if someone can point me in the right direction.

Operating System

Linux

Operating System Details

No response

FastAPI Version

0.109.2

Pydantic Version

2.8.2

Python Version

3.12.4

Additional Context

No response

[jgould22]

however it is possible and correct to upload a file omitting the name in the multipart form post request.

In starlette's case it is not. You can read more here https://www.starlette.io/requests/#Request%20Files

As settled in RFC-7578: 4.2, form-data content part that contains file assumed to have name and filename fields in Content-Disposition header: Content-Disposition: form-data; name="user"; filename="somefile". Though filename field is optional according to RFC-7578, it helps Starlette to differentiate which data should be treated as file. If filename field was supplied, UploadFile object will be created to access underlying file, otherwise form-data part will be parsed and available as a raw string.

So this is more of a starlette thing than a FastAPI thing.

[4c0n]

Even then, FastAPI does not handle it correctly do you not agree? This validation error states it is expecting an instance of UploadFile and is receiving a string. Which is weird, but apparently can be expected.

[jgould22]

I mean, sure but that is because by not including the filename starlette has assumed it is supposed to be a str and you have told fastapi that you wanted a file.

There is not much for fastapi to do here because this choice / processing is done in starlette before the value reaches fastapi's validation code.

[4c0n]

Sure that sounds reasonable, but then why would the filename property of the FastAPI version of UploadFile need to be None by default, considering it will always be set?
I don't really need to support uploads without a name, but am currently stuck with untestable code and a supposedly completely useless None check of the filename property.

IMO we could make the property not nullable, but that would still produce this weird validation error when an upload without filename is received.
Or we could, for example, raise a proper exception in this case stating that it is not supported to upload files without a name.

Another option would be to actually accept the string provided by Starlette and make it available through the UploadFile somehow.

Sure there's also the option to accept it for what it is, but I fail to see how that's very helpful for developers.