Registry / web-framework / multer

multer

JSON →
library2.1.1jsnpmunverified

Multer is a Node.js middleware for handling `multipart/form-data`, primarily used for file uploads in web applications built with frameworks like Express. It is built on top of `busboy` for efficient streaming and processing of incoming form data. The current stable version is 2.1.1. Multer maintains an active release and security cadence, with multiple patches in recent minor versions (e.g., 2.0.1 through 2.1.1) addressing critical security vulnerabilities (CVEs). Its key differentiators include its robust handling of various file upload scenarios (single, array, multiple fields) and its straightforward API, making it a standard choice for file uploads in the Node.js ecosystem. It explicitly only processes `multipart/form-data` and ignores other content types.

npm install multer
INSTALL
IMPORT
SIG · MULTER
M
multer
web-frameworkjavascriptv2.1.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

multer
import multer from 'multer'; // or const multer = require('multer');
import { multer } from 'multer';
Multer is typically imported as a default export for CommonJS (`require`) and often as a default or namespace import for ESM. The primary function `multer()` is then called to configure the middleware.
DiskStorage
import multer, { DiskStorageOptions, StorageEngine } from 'multer'; const storage = multer.diskStorage({ destination: (req, file, cb) => { /* ... */ }, filename: (req, file, cb) => { /* ... */ } });
import { diskStorage } from 'multer';
DiskStorage is a method on the default `multer` export, used for configuring file storage on disk. For TypeScript, import `DiskStorageOptions` and `StorageEngine` types separately.
MulterError
import multer, { MulterError } from 'multer'; app.post('/upload', upload.single('file'), (err, req, res, next) => { if (err instanceof MulterError) { /* handle Multer-specific error */ } });
import { Error } from 'multer';
Use the `MulterError` class to specifically catch and handle errors thrown by Multer middleware, distinguishing them from other application errors.

This quickstart demonstrates setting up an Express server to handle a single file upload using Multer's disk storage, including basic error handling and a 5MB file size limit. It configures the destination and filename for uploaded files.

import express from 'express'; import multer from 'multer'; import path from 'path'; import { fileURLToPath } from 'url'; import { dirname } from 'path'; import fs from 'fs'; const __filename = fileURLToPath(import.meta.url); const __dirname = dirname(__filename); const app = express(); const PORT = process.env.PORT || 3000; // Ensure the uploads directory exists const uploadsDir = path.join(__dirname, 'uploads'); if (!fs.existsSync(uploadsDir)) { fs.mkdirSync(uploadsDir); } // Configure disk storage for Multer const storage = multer.diskStorage({ destination: (req, file, cb) => { cb(null, uploadsDir); }, filename: (req, file, cb) => { cb(null, Date.now() + '-' + file.originalname); } }); const upload = multer({ storage: storage, limits: { fileSize: 5 * 1024 * 1024 } }); // 5MB limit // Basic HTML form for upload app.get('/', (req, res) => { res.send(` <form action="/upload-profile" method="post" enctype="multipart/form-data"> <input type="file" name="avatar" /> <button type="submit">Upload Avatar</button> </form> `); }); // Route to handle single file upload app.post('/upload-profile', upload.single('avatar'), (req, res) => { if (!req.file) { return res.status(400).send('No file uploaded.'); } res.send(`File uploaded successfully: ${req.file.filename}`); }); // Global error handler for Multer errors app.use((err, req, res, next) => { if (err instanceof multer.MulterError) { return res.status(500).send(`Multer error: ${err.message}`); } else if (err) { return res.status(500).send(`Unknown error: ${err.message}`); } next(); }); app.listen(PORT, () => { console.log(`Server running on http://localhost:${PORT}`); });
Debug
Known issues
breakingVersion 2.0.0 introduced a breaking change by raising the minimum supported Node.js version to 10.16.0. Projects on older Node.js versions must upgrade Node.js to use Multer v2 and above.
fix
Upgrade your Node.js runtime to version 10.16.0 or higher. For ESM module usage, Node.js 12+ is generally recommended.
affects: >=2.0.0
breakingMultiple critical security vulnerabilities (CVEs) have been patched in recent minor releases, including CVE-2026-3520 (v2.1.1), CVE-2026-2359, CVE-2026-3304 (v2.1.0), CVE-2025-7338 (v2.0.2), CVE-2025-48997, CVE-2025-47935, and CVE-2025-47944 (v2.0.0). These could lead to denial of service or other critical impacts.
fix
Always upgrade to the latest stable version of Multer to receive critical security patches. Specifically, upgrade to v2.1.1 or newer immediately.
affects: <2.1.1
gotchaMulter will only process forms with `enctype="multipart/form-data"`. If your HTML form is missing this attribute, Multer will not parse any files or text fields from the request body.
fix
Ensure your HTML form explicitly sets `enctype="multipart/form-data"` for file uploads or multipart text-only forms.
affects: >=0.1.0
gotchaNever use Multer as a global middleware (e.g., `app.use(multer().any())`). This can expose your application to security risks, as malicious users could upload files to unintended routes, potentially filling disk space or exploiting other vulnerabilities. Always apply Multer middleware to specific routes where file uploads are expected and handled.
fix
Only apply Multer middleware directly to routes that are specifically designed to handle file uploads. For example: `app.post('/upload', upload.single('file'), handler);`
affects: >=0.1.0
gotchaWhen configuring custom `DiskStorage`, the `filename` function must return a complete filename, including the file extension. Multer does not automatically append extensions.
fix
In your `diskStorage` `filename` function, ensure you construct the filename with the appropriate extension, often derived from `file.originalname` or `file.mimetype`. Example: `cb(null, Date.now() + path.extname(file.originalname));`
affects: >=0.1.0
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'filename')
`req.file` or `req.files` is undefined, meaning no file was uploaded or processed by Multer.
fix
Check the HTML form's `enctype="multipart/form-data"` and the `name` attribute of the file input match the Multer middleware (e.g., `upload.single('avatar')` for `<input name='avatar'>`). Ensure the Multer middleware is correctly applied to the route.
MulterError: Unexpected field
The field name provided in the file input (`name` attribute) does not match the field name configured in the Multer middleware (e.g., `upload.single('photo')` but form has `name='avatar'`).
fix
Verify that the `name` attribute of your HTML file input(s) exactly matches the field name(s) specified in your Multer middleware calls (e.g., `upload.single('avatar')`, `upload.array('photos')`, `upload.fields([{ name: 'gallery' }])`).
MulterError: File too large
The uploaded file's size exceeds the configured `limits.fileSize` in your Multer options.
fix
Increase the `fileSize` limit in your Multer configuration object (e.g., `multer({ limits: { fileSize: 10 * 1024 * 1024 } })` for 10MB) or adjust your application's requirements.
Error: Unsupported Media Type
The request's `Content-Type` header is not `multipart/form-data`, but Multer middleware was applied.
fix
Ensure the client-side form or API request has the `Content-Type` header set correctly to `multipart/form-data`. For HTML forms, this means adding `enctype="multipart/form-data"`.
Upgrade
Version history
2.1.1latest on npm
Audit
Dependencies
expressoptionalCommonly used as a middleware within Express.js applications, though not a direct runtime dependency of the Multer package itself.
busboyrequiredMulter is built on top of busboy for efficient multipart stream parsing. It's a direct runtime dependency but usually not interacted with directly by users.
Agent activity
10 hits · last 30 days
node
10
Resources
multer — npm install multer · libregistry