multer 2.0 Migration Guide — Breaking Changes from 1.4.5-lts.1 to 2.x

5 min read · Updated April 10, 2026 · Safe version: multer@2.1.1

Most multer 1.x apps migrate to 2.x with just a version bump. There are three areas with actual breaking changes: error handling, fileFilter callback, and peer dependency compatibility with storage engines.

Step 1 — Update the version

npm install multer@2.1.1

# Verify
npm list multer
# Should show multer@2.1.1

Step 2 — Check these breaking changes

Breaking change 1 — fileFilter callback

The fileFilter callback signature changed in 2.x. If you use a custom fileFilter, update it:

// multer 1.x
const upload = multer({
  fileFilter: (req, file, cb) => {
    if (file.mimetype === "image/jpeg") {
      cb(null, true);
    } else {
      cb(new Error("Only JPEG allowed"), false);
    }
  }
});

// multer 2.x — same signature, but error handling changed
// cb(new Error(...)) now emits the error differently
// Test your error handling paths after upgrading

Breaking change 2 — Error handling

In multer 2.x, errors from file size limits and fileFilter rejections are surfaced differently. Test these paths in your app:

// Express error handler — test this still catches multer errors
app.use((err, req, res, next) => {
  if (err instanceof multer.MulterError) {
    // LIMIT_FILE_SIZE, LIMIT_FILE_COUNT etc — still work in 2.x
    return res.status(400).json({ error: err.code });
  }
  next(err);
});

Breaking change 3 — Storage engine compatibility

# If using multer-s3, upgrade both together
npm install multer@2.1.1 multer-s3@3

# Check what version of multer-s3 you have
npm list multer-s3

Step 3 — Run your tests

# After upgrading
npm install
npm test

# Specifically test:
# 1. File upload success paths
# 2. File size limit errors
# 3. File type rejection (if using fileFilter)
# 4. Multiple file uploads
# 5. Memory storage vs disk storage

Node.js version requirement

multer 2.x requires Node.js 10.16.0 or later. Check your version: node --version. If you are on Node 8 or earlier, upgrade Node first.

Version history — what each version fixed

Common errors when upgrading multer 1.x to 2.x

These are the exact error messages developers hit when upgrading multer. Each one has a specific fix.

Error: Cannot find module 'multer/lib/make-middleware'

Error: Cannot find module 'multer/lib/make-middleware'
Require stack:
- /app/node_modules/multer-s3/lib/index.js

Cause: multer-s3 v2 only works with multer 1.x. Fix: upgrade multer-s3 to v3 alongside multer 2.x.

npm install multer@2.1.1 multer-s3@3

Error: req.file is uined after upgrade

TypeError: Cannot read properties of undefined (reading 'path')
    at uploadHandler (/app/routes/upload.js:12:25)

Cause: fileFilter callback error handling changed in 2.x. If your fileFilter calls cb(new Error(...)), the file object may not be attached in the same way. Test your fileFilter paths explicitly after upgrading.

Error: MulterError: LIMIT_UNEXPECTED_FILE

MulterError: Unexpected field
    at makeError (/app/node_modules/multer/lib/make-error.js:12:19)

Cause: Field name mismatch between your form and your multer config. This error exists in both 1.x and 2.x — check that your HTML input name matches the field name in upload.single('fieldname').

Before and after — code comparison

// multer 1.x — still works but vulnerable
const multer = require('multer');
const upload = multer({ dest: 'uploads/' });
// package.json: "multer": "^1.4.5-lts.1"  ← VULNERABLE

// multer 2.x — safe, samt multer = require('multer');
const upload = multer({ dest: 'uploads/' });
// package.json: "multer": "^2.1.1"  ← SAFE

// The API is identical for basic usage
// Only difference: error handling and fileFilter edge cases

multer 2.x with Express — compatibility

multer 2.x is fully compatible with Express 4.x and 5.x. The middleware API is unchanged.

const express = require('express');
const multer = require('multer');  // 2.1.1

const app = express();
const upload = multer({ dest: 'uploads/' });

// Single file — identical in 1.x and 2.x
app.post('/upload', upload.single('file'), (req, res) => {
  res.json({ filename: req.file.filename });
});

// Multiple files — identical in 1.x and 2.x
app.post('/photos', upload.array('photos', 12), (req, res) => {
  res.json({ count: req.files.length });
});

If you are seeing errors with Express and multer 2.x, the issue is almost always a storage engine compatibility problem (multer-s3, multer-gridfs-storage) rather than Express itself. Check your storage engine version first.

After updating - verify your fix

Run these commands to confirm the update worked:

# npm projects
npm list multer
npm list node-fetch

# Python projects
pip show fastapi | grep Version
pip show flask | grep Version

# Scan your full manifest for other vulnerabilities
# Paste your requirements.txt or package.json into PackageFix

Paste your full manifest into PackageFix to check all packages at once.

Vulnerability data sourced from the OSV database and public package registries. Always test dependency updates in a staging environment before deploying to production. PackageFix provides these tools for informational purposes only and cannot guarantee that pinned versions are free from undiscovered vulnerabilities.