Multer rejects the upload with Unexpected field
MulterError: Unexpected fieldShort 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.
Fix it fast
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); });2Match what you see, then jump to its fix
- 1
err.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
err.field is the correct name, but the form sends several files under itMore files arrive in a field than the route acceptsFix - 3
The form is meant for text only, yet a file input is inside itThe route uses upload.none() but the form sends a fileFix - 4
The route uses upload.fields([...]) and err.field is a field the form really needsA field is missing from the upload.fields() listFix
- 1
What does the error look like?
MulterError: Unexpected fieldMulterError: Unexpected file fieldcode: '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/avatarConfirmed by github.com
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/photosConfirmed by raw.githubusercontent.com
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/profileConfirmed by raw.githubusercontent.com
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
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
Back end
Angular app shows 'Cannot GET /' when served by a Node.js server
Cannot GET /dashboard
Cannot GET / is Express saying no route or file matches the request.
3 causes, each with a fixBack end
Axios call from a React app comes back 404
404 (Not Found)
Status code 404 means a server answered, but it has nothing at that path.
3 causes, each with a fixBack end
bcrypt.hash throws 'data and salt arguments required'
Error: data and hash arguments required
The bcrypt package throws this when hash gets null or undefined for the password or for the salt.
4 causes, each with a fixBack end
bcryptjs rejects hash() or compare() with Illegal arguments
Error: Illegal arguments: string, undefined
bcryptjs checks the types of its two arguments and, when either is wrong, throws Illegal arguments followed by the typeof of the first and the second.
3 causes, each with a fixBack end
Express warns 'body-parser deprecated undefined extended'
body-parser deprecated undefined extended
The warning appears because urlencoded() was called without the extended option, which body-parser 1.x has warned about since version 1.4.0.
3 causes, each with a fixBack end
Browser blocks a stylesheet or script: MIME type mismatch with nosniff
The Network tab shows the asset URL answered with Content-Type text/html
With X-Content-Type-Options: nosniff the browser accepts a stylesheet only as text/css and a script only as a JavaScript type.
3 causes, each with a fix