How to handle file uploads in Express.js with Multer?

Multer is Node.js middleware for Express that parses multipart/form-data requests, turning raw binary streams into req.file or req.files objects your route handlers can actually use.

#Theory

#TL;DR

• Multer acts like a mailroom clerk: it opens the multipart request, separates form fields from file data, and hands both to your route handler
• Express parses JSON and URL-encoded bodies by default but ignores file uploads entirely. Multer fills that gap
• upload.single('field') for one file, upload.array('field', n) for multiple from the same field, upload.fields([...]) for mixed
• memoryStorage() keeps files in RAM as a Buffer, diskStorage() writes to disk. Pick based on what you do next with the file
• Always set limits and fileFilter in production. Without them, anyone can send a 10GB "image" to your server

#Quick example

upload.single('avatar') is middleware. It runs before your handler, parses the stream, and populates req.file. Your handler just reads the result.

#Why Express alone won't work

Express parses application/json and application/x-www-form-urlencoded bodies natively. But file uploads arrive as multipart/form-data, a single binary stream split by boundary markers in the Content-Type header. Express ignores this stream entirely.

Multer hooks into the middleware chain, reads the raw stream with Busboy under the hood, splits it at those boundaries, buffers file chunks into Buffer objects, and decodes text fields. After Multer runs, your route has req.body for fields and req.file for the file.

#Storage options

Two built-in options:

multer.memoryStorage() holds the file in RAM as req.file.buffer. Good for processing immediately: resize with sharp, upload to S3, run OCR. Bad for large files or high traffic. 100 users uploading 50MB each equals a 5GB RAM spike.

multer.diskStorage({ destination, filename }) writes directly to disk. Good for files you serve statically or process later. You control the path and filename via callbacks.

Using file.originalname directly as the filename causes collisions. Two users uploading avatar.jpg overwrite each other. UUID or Date.now() + random fixes this.

#When to use each method

• One file from one form field: upload.single('fieldName')
• Several files from the same field: upload.array('photos', 5) (second arg is max count)
• Files from different fields: upload.fields([{name: 'avatar', maxCount: 1}, {name: 'docs', maxCount: 3}])
• No files, just form fields: skip Multer, use express.urlencoded()
• Process in memory then push to S3: memoryStorage()
• Serve files from disk: diskStorage()

#Validation and limits

Without limits, Multer buffers whatever comes in. A limits object and a fileFilter function cover the two main attack vectors:

fileFilter runs before the file is buffered. Passing false rejects the file. Passing an Error sends it downstream as an error you catch with error-handling middleware.

One thing to know: mimetype comes from the client's Content-Type header. An attacker can send image/jpeg for a PHP file. For real security, check magic bytes in the buffer. JPEG starts with 0xFF 0xD8, PNG with 0x89 0x50 0x4E 0x47. Read req.file.buffer.slice(0, 4) and compare.

#Error handling

Multer throws two kinds of errors: multer.MulterError for built-in limits and regular Error for custom rejections from fileFilter. Handle both in one middleware:

If you use diskStorage and a file saves to disk but the request later fails, clean it up with fs.unlink(req.file.path, () => {}).

#Common mistakes

Forgetting enctype="multipart/form-data" on the HTML form

Without it, the browser sends application/x-www-form-urlencoded. Multer skips it, req.file is undefined, and your handler crashes on req.file.originalname.

No limits in production

A 2GB file sent to an endpoint with memoryStorage() and no fileSize limit gets buffered entirely in RAM. Node dies. Add limits: { fileSize: 10 * 1024 * 1024 } at minimum.

Using cb(null, false) in fileFilter without throwing

When fileFilter calls cb(null, false), the file is rejected quietly. req.file is undefined. Your handler then crashes reading req.file.size. I've seen this burn teams for an hour debugging why uploads disappeared without any error. Throw instead: cb(new Error('Invalid file type'), false).

Storing original filename on disk

cb(null, file.originalname) causes collisions. Ten users uploading photo.jpg all overwrite the same file. Use uuidv4() or Date.now() + '-' + Math.round(Math.random() * 1e9).

Using memoryStorage for files you just write to disk anyway

If your handler does fs.writeFile('uploads/' + file.originalname, req.file.buffer), you buffered the file in RAM first, then wrote it. Use diskStorage instead. Multer streams it directly to disk and skips the RAM allocation entirely.

#Real-world usage

• Profile picture APIs: memoryStorage() then s3.putObject({ Body: req.file.buffer })
• NestJS: @UseInterceptors(FileInterceptor('file')) wraps Multer, same behavior underneath
• Strapi CMS: uses diskStorage for its media library uploads
• Image processing pipelines: memoryStorage() then sharp(req.file.buffer).resize(200, 200)

Formidable is an alternative for raw Node.js without Express dependency, with faster stream parsing. Busboy is what Multer uses internally. For maximum throughput when streaming a 1GB file directly to S3 without buffering, drop down to Busboy or @aws-sdk/lib-storage directly.

#Follow-up questions

Q: What is the difference between upload.single(), upload.array(), and upload.fields()?
A: single('avatar') expects one file in the named field and puts it in req.file. array('photos', 5) takes multiple files from the same field and puts them in req.files as an array. fields([{name:'avatar'}, {name:'docs'}]) handles files from different field names and puts them in req.files as an object keyed by field name.

Q: How do you handle large file uploads without crashing Node?
A: memoryStorage buffers the whole file in RAM. For anything over a few MB at scale, use diskStorage so Multer streams directly to disk. For S3, build a stream pipeline with @aws-sdk/lib-storage Upload instead of buffering the entire file first.

Q: How do you validate the actual file type, not just the MIME type?
A: Check magic bytes in the buffer. JPEG starts with 0xFF 0xD8, PNG with 0x89 0x50 0x4E 0x47. Read req.file.buffer.slice(0, 4) and compare. The mimetype field comes from the client header and can be spoofed freely.

Q: What happens if a file passes fileFilter but disk storage fails mid-write?
A: Multer may have partially written the file. Check req.file.path in your error handler and call fs.unlink(req.file.path, () => {}) to clean it up. A try/finally block in your handler works well here.

Q: Why does Multer double-buffer when using memoryStorage with S3?
A: Multer collects all incoming chunks into one Buffer via Busboy. Then you create a Readable stream from that buffer to pass to s3.putObject. That is two copies in memory. To avoid it, skip Multer for large S3 uploads and pipe req directly through @aws-sdk/lib-storage Upload with streaming enabled.

#Examples

#Basic: single file upload with memory storage

upload.single('avatar') runs as middleware before your handler. If the form field name doesn't match 'avatar', req.file is undefined. Always guard with if (!req.file).

#Intermediate: avatar upload with disk storage, validation, and error handling

UUID filenames prevent collisions when multiple users upload files with the same name. The error-handling middleware at the end catches both Multer built-in errors and custom ones from fileFilter. Without it, fileFilter errors surface as unhandled 500s.

#Advanced: file upload directly to S3 from memory

memoryStorage is the right choice here because the buffer is needed to send to S3 and the file never touches disk. For files larger than 50MB, switch to @aws-sdk/lib-storage Upload with streaming. It handles multipart S3 upload without holding the entire file in RAM.