Fix HTTPException: 422 Unprocessable Entity: value is not a valid UploadFile in FastAPI

This error occurs when a file upload endpoint expects a multipart form field but receives the data in the wrong format, or the endpoint parameter is not correctly annotated with File() or UploadFile. Fix it by using the correct type annotation with File(...) as the default and ensuring the client sends the file as multipart/form-data.

Reading the Stack Trace

Here's what each line means:

• File "/app/src/routes/uploads.py", line 14, in upload_file: The endpoint function is expecting an UploadFile parameter but FastAPI could not validate the incoming data as a file upload.
• File "/app/venv/lib/python3.11/site-packages/fastapi/routing.py", line 163, in run_endpoint_function: FastAPI's request validation rejected the input before the endpoint function could execute.
• value is not a valid UploadFile (type=type_error): The incoming request body was not sent as multipart/form-data or the field name did not match the parameter name.

Common Causes

@app.post("/upload")
async def upload_file(file: UploadFile):
    contents = await file.read()
    return {"filename": file.filename, "size": len(contents)}

# Client-side JavaScript
fetch('/upload', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ file: fileData })
});

# Client sends field named 'document'
# Server expects field named 'file'
@app.post("/upload")
async def upload_file(file: UploadFile = File(...)):
    contents = await file.read()
    return {"filename": file.filename}

The Fix

Add File(...) as the default value for the file parameter so FastAPI correctly parses it from multipart/form-data. Also add content type validation to reject unsupported file types early. Ensure the client sends the request using FormData with the matching field name.

@app.post("/upload")
async def upload_file(file: UploadFile):
    contents = await file.read()
    return {"filename": file.filename, "size": len(contents)}

from fastapi import File, UploadFile

@app.post("/upload")
async def upload_file(file: UploadFile = File(...)):
    if file.content_type not in ["image/png", "image/jpeg", "application/pdf"]:
        raise HTTPException(status_code=400, detail="Unsupported file type")
    contents = await file.read()
    return {"filename": file.filename, "size": len(contents)}

Testing the Fix

import pytest
from io import BytesIO
from fastapi.testclient import TestClient
from app.main import app

client = TestClient(app)


def test_upload_valid_file():
    file_content = b"fake image content"
    response = client.post(
        "/upload",
        files={"file": ("test.png", BytesIO(file_content), "image/png")},
    )
    assert response.status_code == 200
    assert response.json()["filename"] == "test.png"
    assert response.json()["size"] == len(file_content)


def test_upload_unsupported_file_type():
    response = client.post(
        "/upload",
        files={"file": ("test.exe", BytesIO(b"binary"), "application/octet-stream")},
    )
    assert response.status_code == 400


def test_upload_without_file_returns_422():
    response = client.post("/upload")
    assert response.status_code == 422

Run your tests:

pytest tests/test_uploads.py -v

Pushing Through CI/CD

git checkout -b fix/fastapi-file-upload,git add src/routes/uploads.py tests/test_uploads.py,git commit -m "fix: add File() annotation and content type validation for uploads",git push origin fix/fastapi-file-upload

Your CI config should look something like this:

name: CI
on:
  pull_request:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
          cache: 'pip'
      - run: pip install -r requirements.txt
      - run: pytest --tb=short -q

The Full Manual Process: 18 Steps

Here's every step you just went through to fix this one bug:

1. Notice the error alert or see it in your monitoring tool
2. Open the error dashboard and read the stack trace
3. Identify the file and line number from the stack trace
4. Open your IDE and navigate to the file
5. Read the surrounding code to understand context
6. Reproduce the error locally
7. Identify the root cause
8. Write the fix
9. Run the test suite locally
10. Fix any failing tests
11. Write new tests covering the edge case
12. Run the full test suite again
13. Create a new git branch
14. Commit and push your changes
15. Open a pull request
16. Wait for code review
17. Merge and deploy to production
18. Monitor production to confirm the error is resolved

Total time: 30-60 minutes. For one bug.

pip install bugstack

import bugstack

bugstack.init(api_key=os.environ["BUGSTACK_API_KEY"])

Deploying the Fix (Manual Path)

1. Run the test suite locally to confirm file uploads are accepted and validated.
2. Open a pull request with the File() annotation fix.
3. Wait for CI checks to pass on the PR.
4. Have a teammate review and approve the PR.
5. Merge to main and verify file uploads work in staging.

Frequently Asked Questions