Multipart/Form-Data Encoding: File Uploads from Browser to Server

multipart/form-data is an HTTP encoding format defined in RFC 7578 for submitting forms that include files. Unlike application/x-www-form-urlencoded (which encodes all form values as key=value&key2=value2), multipart/form-data separates each field with a unique boundary string. This design allows files to be transmitted as raw binary without the 3x size overhead of URL encoding and without the 33% overhead of base64 encoding.

The boundary string is a random sequence of characters that does not appear in any of the form values or file contents. The Content-Type header for the request must include this boundary: Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryABC123. Each part of the body starts with '--' followed by the boundary, then the part headers (Content-Disposition, Content-Type for binary parts), a blank line, and the field value or file bytes. The final boundary ends with '--' appended after the boundary string to signal the end of the multipart body.

Text fields in multipart/form-data have a Content-Disposition header of form-data; name="fieldName" and no Content-Type header (implied text/plain). File fields add filename="originalName.jpg" to the Content-Disposition and include a Content-Type header matching the file's MIME type. These differences are how parsers like multer distinguish between req.body (text fields) and req.file/req.files (file fields).

The browser's FormData API generates the boundary string automatically and sets the correct Content-Type header when the FormData object is used as the fetch() or XMLHttpRequest body. Manually constructing a multipart body is error-prone because: (1) the boundary must be unique enough to not appear in binary file content, (2) line endings must be CRLF (\r\n), not just LF (\n), and (3) the header-body separator is a blank CRLF line. Libraries like form-data (npm) handle this correctly for Node.js API clients.

When multer's req.file is undefined, the first check is whether the field name in upload.single('fieldname') exactly matches the key used in formData.append('fieldname', file). They are case-sensitive. The second check is whether the request actually has the correct Content-Type header with the boundary parameter. In browser devtools, go to Network, select the upload request, and look at the Request Headers — you should see Content-Type: multipart/form-data; boundary=....

If the Content-Type header shows multipart/form-data without a boundary= parameter, the boundary was stripped. This is caused by manually setting the Content-Type header, which removes the automatically generated boundary. The fix is to delete the explicit Content-Type header and let the browser or form-data library set it automatically.

When express.json() is applied globally before multer in the middleware stack, it may consume the request stream for multipart requests, leaving an empty or already-consumed stream for multer. Express.json() and express.urlencoded() should be applied only to routes that need them, not globally before all routes. Alternatively, use multer before express.json() for upload routes, or configure express.json() to skip requests with Content-Type multipart/form-data.

For '413 Payload Too Large' errors from nginx (not from multer), check your nginx client_max_body_size setting. The default is 1 MB. If you want to accept files larger than 1 MB, set client_max_body_size 50M; in the nginx location block for upload routes. The 413 from nginx is returned before the request reaches your Node.js server, so multer never sees the request. Verify which layer is returning 413 by checking the response headers — nginx 413 responses include Server: nginx.

For browser-based file uploads, use the FormData API. Create a new FormData(), append the file with formData.append('fieldName', fileInput.files[0]), and pass the FormData as the fetch body without setting Content-Type. The browser automatically generates a unique boundary and sets the complete Content-Type header. For multiple files, use formData.append('photos', file) multiple times with the same field name, or use formData.append('photo1', file1), formData.append('photo2', file2) for distinct field names.

On the server, multer provides three storage engines. multer.memoryStorage() stores the file in req.file.buffer as a Buffer — convenient for small files and immediate processing but risky for large files that exhaust memory. multer.diskStorage({destination, filename}) saves files to disk — better for large files but requires cleanup. For cloud storage (AWS S3, Google Cloud Storage), use multer-s3 or multer-storage-cloudinary, which stream directly to cloud storage without buffering on your server.

For non-browser HTTP clients (Node.js API client, curl, Postman, mobile apps), use the form-data npm package. Create a new FormData instance (from the form-data package), append fields and files with .append(), and pass it as the request body with the headers from form.getHeaders() which includes the correct Content-Type with boundary. In curl: curl -F 'avatar=@/path/to/file.jpg' http://localhost:3000/api/upload — the -F flag handles multipart encoding and boundary generation automatically.

For validating file types securely, do not rely solely on the MIME type from the request — clients can set it to any value. Read the first few bytes of the file buffer and check the magic bytes. JPEG starts with FF D8 FF, PNG starts with 89 50 4E 47, PDF starts with 25 50 44 46. The file-type npm package provides magic byte detection for over 60 file formats: const type = await fileTypeFromBuffer(req.file.buffer). Validate both the claimed MIME type and the detected type from magic bytes.

Boundary string collisions are theoretically possible but extremely unlikely with properly generated boundaries. The browser generates boundaries using a prefix like '----WebKitFormBoundary' followed by 16 random characters, giving approximately 2^96 possible values. If the boundary string happens to appear in the binary file content, the multipart parser will incorrectly split the file at that position. This is why boundaries must be randomly generated, not fixed strings like '--boundary--'.

For very large file uploads (hundreds of MB or several GB), streaming to disk or cloud storage is essential. Multer.memoryStorage() buffers the entire file in Node.js heap memory. A 100 MB upload adds 100 MB to your process's memory. For a server with 512 MB of available memory handling 10 concurrent uploads, this is immediately fatal. Use multer.diskStorage() with a temp directory and move files to their final destination after validation, or stream directly to S3 using multer-s3.

Base64-encoded files in multipart bodies are an anti-pattern but sometimes seen in mobile app codebases. Instead of sending the file bytes directly, some clients encode the file as base64 and send it as a text field. This adds 33% overhead and defeats the purpose of multipart encoding. On the server, such fields appear in req.body (not req.file) as a base64 string. Decode with Buffer.from(req.body.fileBase64, 'base64') to get the original bytes. The correct approach is to send the raw file bytes as a file field, not as a base64 text field.

Progress tracking for large uploads requires either the XMLHttpRequest API (which supports progress events) or a client-side chunk upload implementation. The fetch() API does not expose upload progress in browsers as of 2026. For progress tracking with fetch, use the ReadableStream request body with a custom stream that tracks bytes written. For simpler implementation, use XMLHttpRequest: xhr.upload.addEventListener('progress', e => setProgress(e.loaded / e.total * 100)).

Not removing files after processing is a common disk exhaustion bug. When using multer.diskStorage(), uploaded files are saved to the destination directory and remain there until your code deletes them. If a validation step rejects the file and returns an error without deleting the uploaded file, the temp directory gradually fills. Use fs.unlink(req.file.path) in error handlers and after successful processing. Set up a cron job to clean old files from the upload temp directory as a safety net.

Trusting the originalname from multer without sanitization is a path traversal vulnerability. multer passes req.file.originalname as-is from the client. An attacker can set the filename to '../../etc/passwd' or any other path. Never use originalname directly as a filesystem path. Generate a new filename with a UUID: const safeName = randomUUID() + path.extname(req.file.originalname). Validate the extension against an allowlist before using it.

Not setting a file size limit in multer exposes the server to denial-of-service attacks. Without a limit, an attacker can send a request claiming to be a 10 MB file and actually stream 100 GB of data. Multer will keep accepting data until the disk or memory is exhausted. Always set limits.fileSize to a reasonable maximum for your use case. Combine this with an nginx client_max_body_size setting as a first line of defense.

Parsing multipart form data with a JSON body parser is a common misconfiguration. If you have app.use(express.json()) applied globally in Express, it runs on every request including multipart uploads. For multipart requests, express.json() reads the stream (because it tries to parse it) and either fails silently or consumes the request body before multer can read it. The fix is to apply body parsing middleware selectively: either use router-level middleware, or skip body parsing when Content-Type is multipart/form-data.

Set explicit limits for everything multer controls: fileSize (maximum bytes per file), files (maximum number of files), fields (maximum number of text fields), fieldSize (maximum text field value size in bytes). These limits prevent both accidental large uploads and intentional denial-of-service attacks. Document these limits in your API reference so clients know what to expect.

For files that need to be served back to users, never store uploaded files with their original names in a public directory. This creates two vulnerabilities: (1) path traversal if the filename contains ../, (2) stored XSS if the filename contains HTML and it is displayed unencoded, and (3) file overwriting if two users upload files with the same name. Generate a UUID-based filename, store the original name in your database for display, and serve files via a route that looks up the UUID and streams the file.

For compliance (GDPR, HIPAA, SOC 2), encrypt files at rest in your storage layer. S3 server-side encryption (SSE-S3 or SSE-KMS) is easy to enable and encrypts all uploaded objects transparently. For highly sensitive files, encrypt client-side before upload using SubtleCrypto (AES-256-GCM) and store the encryption key separately. Log all file uploads with timestamp, user ID, filename, size, and IP address for audit trail requirements.

Test your multipart implementation with: zero-byte files (should upload successfully or be rejected with a clear message), files at exactly the size limit and one byte over (tests boundary conditions), files with Unicode filenames ('照片.jpg', 'фото.jpg'), files with path characters in the name ('../etc/passwd'), files whose extension does not match their magic bytes (JPEG with .png extension), and concurrent uploads from the same user. These test cases cover the most common production failures.