An HTML form contains <input type="file">. Why must it set enctype="multipart/form-data", and what does the browser send differently from the default encoding?

## enctype describes the shape of the body The browser always builds the same entry list first. `enctype` chooses how that list is written into the request body, and there are exactly three values a form may use: `application/x-www-form-urlencoded` (the default), `multipart/form-data`, and `text/plain`. Because it describes a body, `enctype` is meaningful only with `method="post"`; on a GET form it is ignored. ## The default: one flat line of text `application/x-www-form-urlencoded` percent-encodes each name and value, turns spaces into `+`, and joins the pairs with `&`: ``` name=Ada+Lovelace&role=engineer&topic=html&topic=a11y ``` Compact, easy to parse, and perfectly good for text fields — this is why it is the default. What it cannot express is anything *about* a value. There is no slot for a filename, no slot for a per-field content type, and raw bytes would have to be percent-encoded, inflating binary data badly and still leaving nowhere to record what it was. So when a form with a file input is left at the default, the browser submits the **file's name as a plain text value** and the contents are simply not sent. The request succeeds, the server stores an empty or nonsense value, and nothing in the markup looks obviously wrong — which is what makes this a classic bug. ## multipart/form-data: labelled compartments ```html <form action="/avatar" method="post" enctype="multipart/form-data"> <label for="caption">Caption</label> <input id="caption" name="caption"> <label for="photo">Photo</label> <input id="photo" name="photo" type="file"> <button>Upload</button> </form> ``` With this encoding the browser picks a **boundary** — a random token that does not occur in the data — declares it alongside the content type, and writes one part per entry: ``` --boundary123 Content-Disposition: form-data; name="caption" On the beach --boundary123 Content-Disposition: form-data; name="photo"; filename="dog.png" Content-Type: image/png <raw bytes> --boundary123-- ``` Each part carries its own metadata, so binary content passes through untouched and the server learns the original filename and the type the browser guessed. Nothing needs percent-encoding, at the cost of a header block per field, which is why multipart is not the default for ordinary text forms. ## Practical consequences - **Set it on the form, not the input.** A very common mistake is putting `enctype` on the `<input type="file">` or omitting it because the file picker visibly works. The picker always works; only the form's `enctype` decides whether bytes are sent. - **The filename and type are client-supplied.** Both come from the browser and are trivially forged, so a server must never trust the declared `Content-Type` of a part, nor use the supplied filename directly as a path. Treat them as untrusted input like any other field. - **`accept` and `multiple` are separate concerns.** They shape the picker and how many entries the input contributes; neither has any effect on the encoding. - **Per-button override.** `formenctype` on a submit button changes the encoding for that button's activation only, alongside its siblings `formaction`, `formmethod` and `formtarget`. - **`text/plain` exists but is not for production.** It writes `name=value` lines with no escaping, so a value containing a newline is ambiguous. It was intended for `mailto:` debugging, and no server should be parsing it. ## When you submit from script If you take submission over yourself and pass a `FormData` object as a `fetch` body, the browser encodes it as `multipart/form-data` and generates the boundary for you. The mistake to avoid is setting the `Content-Type` header manually: the browser will then use your header, which lacks the boundary token, and the server cannot split the parts — the upload fails with a confusing parse error. Leave the header off and let the browser write it. If you want the urlencoded shape instead, convert with `new URLSearchParams(formData)`, which the browser encodes as `application/x-www-form-urlencoded`; note that this only makes sense when the entries are all text, since URLSearchParams has nowhere to put a file.