CORS preflight and file uploads, explained
A browser sends a CORS preflight only for requests outside a small safelist, and a plain FormData file upload is on that safelist. It's one of the more surprising corners of the spec: the request carrying a binary file looks "complex," so people expect a preflight and don't get one, then add one small thing and suddenly do. We built a minimal cross-origin upload and watched the actual network traffic to show exactly where the line sits.
What counts as a "simple" request
The Fetch spec exempts a request from preflight if it meets all of these:
- The method is
GET,HEAD, orPOST. - The only request headers set are ones the browser would send anyway, plus a short safelist:
Accept,Accept-Language,Content-Language, andContent-Type(with a restricted value). - For
POST,Content-Typeis one of exactly three values:application/x-www-form-urlencoded,multipart/form-data, ortext/plain.
When you build a FormData object and hand it to fetch as the body, the browser sets Content-Type: multipart/form-data; boundary=... for you, and you cannot override it without breaking the upload. That value is on the safelist. So a request that uploads a 10 MB file and a request that submits an empty text field are, as far as preflight is concerned, in the exact same category: simple.
Testing it: a plain upload, then one header
To see the actual wire behavior rather than reason about the spec, we ran two origins locally: a page on http://127.0.0.1:5500 and an API on http://127.0.0.1:5501, with the API logging every request it receives, preflight or not. The page runs the same upload three times with different headers:
async function upload(testCase, extraHeaders) {
const fd = new FormData();
fd.append('file', new Blob(['hello world'], { type: 'text/plain' }), 'hello.txt');
fd.append('note', 'a plain field');
await fetch('http://127.0.0.1:5501/upload?case=' + testCase, {
method: 'POST',
headers: extraHeaders,
body: fd
});
}
await upload('plain-formdata', {});
await upload('with-custom-header', { 'X-Upload-Id': 'abc-123' });
await upload('with-authorization', { 'Authorization': 'Bearer test-token' });
We loaded that page in headless Chromium and read back what the API server actually received, in order:
plain-formdata -> POST
with-custom-header -> OPTIONS
with-custom-header -> POST
with-authorization -> OPTIONS
with-authorization -> POST
The plain upload never generated an OPTIONS request at all. The moment we added X-Upload-Id, a header real apps use to track an in-progress upload for resumability or progress reporting, the browser stopped and preflighted. Adding an Authorization header instead of a tracking ID did the same thing, for the same reason: neither header is on the safelist, so the request is no longer simple.
Why this trips people up
The instinct is to associate "preflight" with request complexity, and a multi-megabyte binary upload feels complex. But preflight isn't about payload size or content, it's about whether the server's existing, non-CORS-aware code could be tricked into doing something by a cross-origin page without ever agreeing to it. A plain HTML form has always been able to POST multipart/form-data to any origin, with no JavaScript and no way for the browser to ask first. fetch preserves that same shape as "safe" precisely because nothing new becomes possible by doing it with fetch instead of a <form>. A custom header, on the other hand, is something only script can set, so the spec treats it as new capability and gates it behind a preflight the target server has to explicitly allow.
What this means through a CORS proxy
corsproxy.dev accepts the file upload as raw, binary-safe bytes and forwards the body to the target unchanged, so a multipart/form-data upload through the proxy works the same way it would direct. The part worth knowing: the API key for a browser call goes in the key query parameter, not a header, and per-request upstream header overrides are also passed as a query parameter (reqHeaders=name:value), not as literal headers your page sets. That means a straightforward upload through corsproxy.dev/proxy?url=...&key=... stays a simple request against corsproxy.dev itself: no custom header, a safelisted Content-Type, no preflight to us. If your own page code adds X-API-Key or any other custom header instead of using the query parameter, you've opted into a preflight against corsproxy.dev that the query-parameter form avoids. Either way the upload still has to fit under the proxy's 10 MB request body limit.
Checking your own upload flow
Open DevTools → Network, filter for OPTIONS, and trigger the upload. If nothing shows up, your request is simple and nothing is gating it. If an OPTIONS appears right before the POST, click it and check its request headers for Access-Control-Request-Headers: that line names the exact header that forced the preflight. It's usually an auth header, a tracking ID, or a Content-Type someone set by hand instead of letting FormData set it. None of that is a bug; it's the server on the other end that then has to answer the preflight correctly, which is the failure mode covered in fixing the Access-Control-Allow-Headers error.