Python Workers: multipart/form-data body parsing fails at ~1 MB (undocumented limit)

[rafaelqntn]

Python Workers: multipart/form-data body parsing fails at ~1 MB (undocumented limit)

What version(s) of the runtime are you using?

Latest deploy target as of 2026-02-20 (compatibility_date = "2024-12-06", compatibility_flags = ["python_workers"]). Also reproducible locally with wrangler dev (wrangler 3.x).

What steps can reproduce the bug?

1. Create a Python Worker that accepts a multipart/form-data file upload (e.g., via FastAPI UploadFile or raw Starlette multipart parsing).
2. Upload a file <= 1024 KB — request reaches the Worker handler normally.
3. Upload a file >= ~1040 KB — request fails before any application code executes.

Binary search confirms the threshold is between 1024 KB and 1040 KB.

Minimal repro using curl:

# Create a 1024 KB test file — succeeds (reaches app code, returns 401 auth error as expected)
dd if=/dev/urandom of=/tmp/test_1024k.bin bs=1024 count=1024
curl -s -o /dev/null -w "%{http_code}" \
  -F "file=@/tmp/test_1024k.bin;type=application/pdf" \
  https://<your-python-worker>/api/documents
# Returns: 401

# Create a 1040 KB test file — fails at body parsing layer
dd if=/dev/urandom of=/tmp/test_1040k.bin bs=1024 count=1040
curl -s -o /dev/null -w "%{http_code}" \
  -F "file=@/tmp/test_1040k.bin;type=application/pdf" \
  https://<your-python-worker>/api/documents
# Returns: 400 — "There was an error parsing the body"

What is the expected behavior?

Per the Workers platform limits documentation (https://developers.cloudflare.com/workers/platform/limits/#request-and-response-limits), the request body size limit is 100 MB on the Free/Pro plan. A ~1 MB multipart upload should succeed and be available to the Worker handler.

What do you see instead?

A 400 Bad Request response with body {"detail":"There was an error parsing the body"} is returned. The error originates from the multipart body parser layer (likely python-multipart / Starlette running under Pyodide in workerd), not from any application code — the Worker's fetch handler is never invoked.

Additional context

This only affects Python Workers. JavaScript/TypeScript Workers on the same account and zone handle the same files without issue (the 100 MB platform limit applies as documented).
The wrangler.jsonc configuration has no body-size-related settings, and the configuration reference (https://developers.cloudflare.com/workers/wrangler/configuration/) does not expose one. The limits key only supports cpu_ms and subrequests.
This limitation is not documented anywhere: not on the Limits page (https://developers.cloudflare.com/workers/platform/limits/), the Known Issues page (https://developers.cloudflare.com/workers/platform/known-issues/), or the Python Workers docs (https://developers.cloudflare.com/workers/languages/python/).
Our MAX_UPLOAD_SIZE_MB app-level env var is set to 10 (10 MB), but the validation code is never reached.
This blocks any real-world file upload use case in Python Workers (e.g., PDF processing, image uploads) for files larger than ~1 MB.

[dom96]

Interesting, can you share your code? This does sound like an issue with starlette/fastapi/python-multipart to me. Does it work if you use the Workers APIs? i.e. the example in https://developers.cloudflare.com/workers/examples/read-post/

[rafaelqntn]

I could reproduce it by starting a local server and sending the same payload to localhost:8787 to a dummy endpoint. My code is never hit, that response happens before my code is executed.

I can provide a small setup for you to try.

[rafaelqntn]

Python Workers: Starlette/FastAPI multipart parsing fails at ~1 MB

Minimal reproduction showing that multipart/form-data uploads > ~1 MB fail when
parsed through Starlette/FastAPI (python-multipart) on Cloudflare Python
Workers, but succeed when using the raw JS request.formData() API directly.

Structure

├── wrangler.jsonc          # Config — switch "main" between the two entries
├── pyproject.toml          # Python deps (fastapi, starlette, python-multipart)
├── package.json            # wrangler dev dependency
├── src/
│   ├── entry_fastapi.py    # FastAPI + asgi.fetch() → FAILS at ~1 MB
│   └── entry_bare.py       # Raw JS request.formData() → WORKS at any size
└── test_upload.sh          # Bash: uploads 512 KB, 1024 KB, 1040 KB, 2048 KB

Prerequisites

• uv
• pywrangler (uv tool install workers-py)
• Node.js ≥ 18
• curl

Quick start

uv run pywrangler sync   # vendor Python deps into python_modules/

Test 1 — FastAPI entry (reproduces the bug)

wrangler.jsonc defaults to "main": "src/entry_fastapi.py".

uv run pywrangler dev     # wait for "Ready on http://localhost:8787"
# in a second terminal:
chmod +x test_upload.sh
./test_upload.sh

Expected output — tests 3 & 4 fail:

── Test 1: 512 KB file ──    HTTP 200  ✓
── Test 2: 1024 KB file ──   HTTP 200  ✓
── Test 3: 1040 KB file ──   HTTP 400  "There was an error parsing the body"
── Test 4: 2048 KB file ──   HTTP 400  "There was an error parsing the body"

Test 2 — Bare entry (proves platform handles it fine)

Edit wrangler.jsonc and change "main" to "src/entry_bare.py", then restart:

uv run pywrangler dev
./test_upload.sh

Expected output — ALL tests pass:

── Test 1: 512 KB file ──    HTTP 200
── Test 2: 1024 KB file ──   HTTP 200
── Test 3: 1040 KB file ──   HTTP 200
── Test 4: 2048 KB file ──   HTTP 200

Root cause

The bug is not in the Workers platform — request.formData() (the JS
runtime API) handles files well beyond 1 MB. The failure occurs in
Starlette's python-multipart parser running under Pyodide inside workerd.

Since every real-world FastAPI/Starlette app on Python Workers goes through this
parser (via the asgi bridge), the ~1 MB limit effectively blocks any
FastAPI-based Worker from accepting uploads larger than ~1 MB.

Environment

• pywrangler / workers-py: latest
• Wrangler: 4.67.0
• compatibility_flags: ["python_workers"]
• compatibility_date: "2026-02-19"
• OS: Linux (WSL2 Ubuntu)

multipart-repro.zip

[ryanking13]

Hi @rafaelqntn, thanks for the report.

The error happens because starlette internally delegates the process of UploadFile to thead when the size if larger than the threshold. We don't support threading because of the runtime limitation, and it was silently failing with throwing the error "can't start new thread".

The workaround for now would be to replace that hard coded threshold to much larger than 1MB. Or there might be a way to set or pass this value, but unfortunately I am not a FastAPI or starlette expert so I am not sure.

from starlette.formparsers import MultiPartParser
MultiPartParser.spool_max_size = 1024 * 1024 * 1024  # keep everything in memory

Meanwhile, I posted an issue in starlette repository: Kludex/starlette#3159

[rafaelqntn]

Thank you for the reply.
I've created a different workaround, but yours looks better; changing a config is more elegant than what I've done.