{"id":10402,"library":"multer","title":"Multer","description":"Multer is a Node.js middleware designed for efficiently handling `multipart/form-data`, primarily used for uploading files. It builds on the busboy library for maximum performance and integrates seamlessly with Express. The current stable version is 2.1.1, with recent releases frequently addressing critical security vulnerabilities (CVEs), indicating active and diligent maintenance.","status":"active","version":"2.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/expressjs/multer","tags":["javascript","form","post","multipart","form-data","formdata","express","middleware"],"install":[{"cmd":"npm install multer","lang":"bash","label":"npm"},{"cmd":"yarn add multer","lang":"bash","label":"yarn"},{"cmd":"pnpm add multer","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Multer primarily uses CommonJS syntax for its usage examples and is fully compatible.","symbol":"multer","correct":"const multer = require('multer')"}],"quickstart":{"code":"const express = require('express');\nconst multer = require('multer');\nconst path = require('path');\nconst fs = require('fs');\n\n// Ensure the 'uploads' directory exists\nconst uploadDir = 'uploads';\nif (!fs.existsSync(uploadDir)) {\n  fs.mkdirSync(uploadDir);\n}\n\n// Configure Multer storage\nconst upload = multer({ dest: uploadDir });\n\nconst app = express();\n\n// Route to handle single file upload\napp.post('/profile', upload.single('avatar'), function (req, res, next) {\n  // req.file is the `avatar` file\n  // req.body will hold the text fields, if there were any\n  if (req.file) {\n    console.log(`File uploaded: ${req.file.originalname} (${req.file.mimetype})`);\n    console.log(`Saved to: ${req.file.path}`);\n  } else {\n    console.log('No file uploaded.');\n  }\n  if (Object.keys(req.body).length > 0) {\n    console.log('Form data:', req.body);\n  }\n  res.send('File upload processed!');\n});\n\nconst PORT = process.env.PORT || 3000;\napp.listen(PORT, () => console.log(`Server running on http://localhost:${PORT}`));\n","lang":"javascript","description":"This example demonstrates how to set up an Express route with Multer to handle a single file upload from a `multipart/form-data` form. It saves the file to a local 'uploads/' directory and makes the file and text fields accessible via `req.file` and `req.body` respectively."},"warnings":[{"fix":"Upgrade your Node.js environment to version 10.16.0 or newer to use Multer v2+.","message":"Multer v2.0.0 and subsequent versions require Node.js version 10.16.0 or higher.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure your HTML form includes `enctype=\"multipart/form-data\"`. For other content types, use appropriate middleware like `express.urlencoded()` or `express.json()`.","message":"Multer exclusively processes `multipart/form-data` content types. It will not parse forms submitted with `application/x-www-form-urlencoded`, `application/json`, or other content types, leaving `req.body` empty for non-file fields.","severity":"gotcha","affected_versions":"all"},{"fix":"To retain original filenames/extensions or customize file naming, use `multer.diskStorage` or `multer.memoryStorage` for advanced control over file storage and naming.","message":"When using `multer({ dest: 'uploads/' })`, files are stored in the specified directory without their original file extensions. They will also have generic names.","severity":"gotcha","affected_versions":"all"},{"fix":"Place Multer middleware (e.g., `upload.single('field')`) before any route handler functions or subsequent middleware that depend on the uploaded file or form data.","message":"Access to `req.file`, `req.files`, and the parsed `req.body` (for text fields) is only available *after* the Multer middleware has successfully processed the request.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-18T00:00:00.000Z","next_check":"2026-07-17T00:00:00.000Z","problems":[{"fix":"Verify that the `name` attribute of your `<input type=\"file\" name=\"fieldName\">` exactly matches the string argument passed to Multer's processing method (e.g., `upload.single('fieldName')`).","cause":"The field name specified in your HTML form's file input does not match the argument provided to Multer's middleware function (e.g., `upload.single('avatar')`).","error":"MulterError: Unexpected field"},{"fix":"Ensure the destination directory (e.g., `uploads/`) is created and accessible by your Node.js application before the server starts. You can do this programmatically: `const fs = require('fs'); if (!fs.existsSync('uploads')) fs.mkdirSync('uploads');`.","cause":"Multer's `dest` option points to a directory that does not exist on the server when a file upload is attempted.","error":"Error: ENOENT: no such file or directory, open 'uploads/...' (or similar file system error)"},{"fix":"Confirm that the HTML form has `enctype=\"multipart/form-data\"`, the file input has a `name` attribute matching Multer's middleware, and a file was actually selected for upload. Add checks for `if (req.file)` before accessing its properties.","cause":"`req.file` (or an element in `req.files`) is undefined in your route handler, typically because no file was uploaded, the file field name was incorrect, or the form's `enctype` was not `multipart/form-data`.","error":"TypeError: Cannot read properties of undefined (reading 'originalname')"},{"fix":"Increase the `fileSize` limit within Multer's configuration, e.g., `multer({ limits: { fileSize: 5 * 1024 * 1024 } })` for a 5MB limit. Alternatively, inform the user about the maximum allowed file size.","cause":"The uploaded file's size exceeds the `fileSize` limit configured in Multer's options (`limits.fileSize`).","error":"MulterError: File too large"}],"ecosystem":"npm"}