Fix MulterError: Unexpected field in Express

This error occurs when the form field name in the multipart request does not match the field name configured in multer. The middleware expects a specific field name but receives a different one. Fix it by ensuring the client form field name matches the multer configuration exactly.

Reading the Stack Trace

Here's what each line means:

• at wrappedFileFilter (/app/node_modules/multer/lib/make-middleware.js:45:19): Multer's file filter rejected the upload because the field name in the request does not match any configured field name.
• at Busboy.<anonymous> (/app/node_modules/multer/lib/make-middleware.js:114:7): Busboy, the underlying multipart parser, detected a file field and passed it to multer's filter which rejected it.
• at HeaderParser._finish (/app/node_modules/busboy/lib/utils.js:312:10): The multipart header parser finished reading the part headers and is now dispatching the field to multer.

Common Causes

// Server expects 'avatar'
const upload = multer({ dest: 'uploads/' });
app.post('/upload', upload.single('avatar'), (req, res) => {
  res.json({ file: req.file });
});

// Client sends 'profileImage'
// <input type="file" name="profileImage" />

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

// Only accepts one file, but form sends multiple
app.post('/upload', upload.single('photo'), (req, res) => {
  res.json({ file: req.file });
});

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

app.post('/upload', upload.single('avatar'), (req, res) => {
  res.json({ file: req.file });
});
// No multer error handler

The Fix

Wrap the multer middleware call manually so you can catch MulterError and return a helpful 400 response that tells the client which field name to use. Also add a file size limit to prevent oversized uploads.

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

app.post('/upload', upload.single('avatar'), (req, res) => {
  res.json({ file: req.file });
});

const multer = require('multer');
const upload = multer({
  dest: 'uploads/',
  limits: { fileSize: 5 * 1024 * 1024 } // 5MB limit
});

app.post('/upload', (req, res) => {
  upload.single('avatar')(req, res, (err) => {
    if (err instanceof multer.MulterError) {
      return res.status(400).json({ error: `Upload error: ${err.message}`, field: err.field });
    }
    if (err) {
      return res.status(500).json({ error: 'Upload failed' });
    }
    if (!req.file) {
      return res.status(400).json({ error: 'No file uploaded. Use field name: avatar' });
    }
    res.json({ file: req.file });
  });
});

Testing the Fix

const request = require('supertest');
const express = require('express');
const multer = require('multer');
const path = require('path');

function createApp() {
  const app = express();
  const upload = multer({ dest: '/tmp/test-uploads/' });
  app.post('/upload', (req, res) => {
    upload.single('avatar')(req, res, (err) => {
      if (err instanceof multer.MulterError) {
        return res.status(400).json({ error: `Upload error: ${err.message}` });
      }
      if (!req.file) {
        return res.status(400).json({ error: 'No file uploaded. Use field name: avatar' });
      }
      res.json({ filename: req.file.originalname });
    });
  });
  return app;
}

describe('POST /upload', () => {
  it('returns 400 for wrong field name', async () => {
    const res = await request(createApp())
      .post('/upload')
      .attach('wrongField', Buffer.from('test'), 'test.txt');
    expect(res.status).toBe(400);
    expect(res.body.error).toContain('Upload error');
  });

  it('uploads successfully with correct field name', async () => {
    const res = await request(createApp())
      .post('/upload')
      .attach('avatar', Buffer.from('test'), 'test.txt');
    expect(res.status).toBe(200);
    expect(res.body.filename).toBe('test.txt');
  });
});

Run your tests:

npx jest --testPathPattern=multer

Pushing Through CI/CD

git checkout -b fix/express-multer-upload-error,git add src/routes/upload.js src/__tests__/multer.test.js,git commit -m "fix: handle MulterError with descriptive 400 response",git push origin fix/express-multer-upload-error

Your CI config should look something like this:

name: CI
on:
  pull_request:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npx jest --coverage
      - run: npm run lint

The Full Manual Process: 18 Steps

Here's every step you just went through to fix this one bug:

1. Notice the error alert or see it in your monitoring tool
2. Open the error dashboard and read the stack trace
3. Identify the file and line number from the stack trace
4. Open your IDE and navigate to the file
5. Read the surrounding code to understand context
6. Reproduce the error locally
7. Identify the root cause
8. Write the fix
9. Run the test suite locally
10. Fix any failing tests
11. Write new tests covering the edge case
12. Run the full test suite again
13. Create a new git branch
14. Commit and push your changes
15. Open a pull request
16. Wait for code review
17. Merge and deploy to production
18. Monitor production to confirm the error is resolved

Total time: 30-60 minutes. For one bug.

npm install bugstack-sdk

const { initBugStack } = require('bugstack-sdk')

initBugStack({ apiKey: process.env.BUGSTACK_API_KEY })

Deploying the Fix (Manual Path)

1. Run the test suite locally to confirm multer errors return descriptive 400 responses.
2. Open a pull request with the upload error handling changes.
3. Wait for CI checks to pass on the PR.
4. Have a teammate review and approve the PR.
5. Merge to main and test file uploads in staging before promoting to production.

Frequently Asked Questions