Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Multer rejects the upload with Unexpected field

ErrorMulterError: Unexpected field

Short answer

Multer throws LIMIT_UNEXPECTED_FILE when a file arrives under a field name your route did not declare, or when more files arrive than the route allows. Read err.field in an error handler: it holds the name the client sent. Then make the client name, the Multer method and its maxCount agree.

  • Applies to Multer 2.x, Express 5, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Add an error handler after the upload route and print the code and the field. Multer passes errors to Express, and a MulterError carries the offending field name, so you see exactly which name the client used.

    app.use((err, req, res, next) => {
      if (err instanceof multer.MulterError) {
        console.log(err.code, err.field);
        return res.status(400).json({ error: err.code, field: err.field });
      }
      next(err);
    });
  2. 2Match what you see, then jump to its fix

    1. 1err.field is a name that does not appear in upload.single(...), upload.array(...) or upload.fields(...)The field name in the form differs from the name in the routeFix
    2. 2err.field is the correct name, but the form sends several files under itMore files arrive in a field than the route acceptsFix
    3. 3The form is meant for text only, yet a file input is inside itThe route uses upload.none() but the form sends a fileFix
    4. 4The route uses upload.fields([...]) and err.field is a field the form really needsA field is missing from the upload.fields() listFix

What does the error look like?

  • MulterError: Unexpected field
  • MulterError: Unexpected file field
  • code: 'LIMIT_UNEXPECTED_FILE'

Cause 1 of 4

The field name in the form differs from the name in the route

1Check

Put the string in your route next to the name attribute of the file input (or the key you append to FormData). Multer only looks for files under the names you list; any other name is unexpected.

// route
app.post('/avatar', upload.single('avatar'), handler);
// client: the key must be exactly 'avatar'
form.append('avatar', fileInput.files[0]);

2Fix

Make both sides use one name. Change the route, or change the name attribute or FormData key, but do not leave them different.

<input type="file" name="avatar">

3Verify

Send the file again with curl using the same field name and expect a 200.

curl -F "avatar=@./photo.jpg" http://localhost:3000/avatar

Confirmed by github.com

Did this fix it?

Cause 2 of 4

More files arrive in a field than the route accepts

1Check

upload.single(name) allows one file in that field, and upload.array(name, maxCount) allows up to maxCount. A file over the limit is reported as unexpected, not as a count error.

grep -n "upload\.\(single\|array\)" -r src/

2Fix

Switch a multi-file input to upload.array and set a maxCount that fits the form.

app.post('/photos', upload.array('photos', 10), handler);

3Verify

Upload two files in the same request; req.files holds both.

curl -F "photos=@a.jpg" -F "photos=@b.jpg" http://localhost:3000/photos

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 3 of 4

The route uses upload.none() but the form sends a file

1Check

upload.none() accepts text fields only. Any file part triggers LIMIT_UNEXPECTED_FILE.

grep -n "upload.none" -r src/

2Fix

Use upload.single, upload.array or upload.fields on routes that receive files, and keep none() for forms that are text only.

app.post('/profile', upload.single('avatar'), handler);

3Verify

Post the form again; the file shows up in req.file.

curl -F "avatar=@./photo.jpg" -F "name=Sam" http://localhost:3000/profile

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 4 of 4

A field is missing from the upload.fields() list

1Check

fields() takes a list of name and maxCount pairs. A file input whose name is not in that list is unexpected.

upload.fields([
  { name: 'avatar', maxCount: 1 },
  { name: 'gallery', maxCount: 8 }
])

2Fix

Add an entry for each file input in the form, with the count you allow.

upload.fields([
  { name: 'avatar', maxCount: 1 },
  { name: 'gallery', maxCount: 8 },
  { name: 'cover', maxCount: 1 }
])

3Verify

Submit the form; req.files is an object with one array per field name.

console.log(Object.keys(req.files));

Confirmed by raw.githubusercontent.com

Did this fix it?

How do I stop it coming back?

  • Keep upload field names in one shared constant used by the route and the client code.
  • Always add an error handler that checks for MulterError so the client gets the field name instead of a stack trace.
  • Set maxCount on array and fields so a limit is a decision, not a surprise.
  • Remember the form needs enctype="multipart/form-data"; Multer does not process other forms.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.