Uploaded files are missing from the request in Express
req.files is undefinedShort answer
Express does not parse file uploads itself, and Multer only handles multipart/form-data. When req.files is undefined, check that the form sends multipart, that the field name matches the Multer call, that you read req.file for single uploads, and that Multer is on the route.
Fix it fast
1Find out which cause you have
Send the upload with curl using an explicit field name. If this works, the server is fine and the browser form or client code is wrong.
curl -i -F "avatar=@./photo.jpg" http://localhost:3000/profile2Match what you see, then jump to its fix
- 1
req.file and req.files are both undefined, no error, and req.body has only text fieldsThe request is not multipart/form-dataFix - 2
error code LIMIT_UNEXPECTED_FILE, or an undefined file when the form field is named differentlyThe field name differs from the one passed to MulterFix - 3
req.files is undefined, yet req.file holds the uploadsingle() fills req.file, not req.filesFix - 4
req.file is undefined on one route only, while another upload route worksThe Multer middleware is not on the route that receives the uploadFix
- 1
What does the error look like?
req.files is undefinedMulterError: LIMIT_UNEXPECTED_FILE
Cause 1 of 4
The request is not multipart/form-data
1Check
Multer ignores any form that is not multipart. An HTML form needs the enctype attribute, and fetch must send a FormData without a hand-set Content-Type.
curl -s -D - -o /dev/null -F "avatar=@./photo.jpg" http://localhost:3000/profile | head -32Fix
Set the encoding on the form, or send a FormData object.
<form action="/profile" method="post" enctype="multipart/form-data">
<input type="file" name="avatar">
</form>3Verify
The handler logs a file object.
curl -F "avatar=@./photo.jpg" http://localhost:3000/profileConfirmed by github.com
Cause 2 of 4
The field name differs from the one passed to Multer
1Check
The name attribute in the form must equal the string in upload.single, upload.array or upload.fields.
grep -rn "upload\.\(single\|array\|fields\)" --include=*.js . | grep -v node_modules2Fix
Make both sides use the same name.
const upload = multer({ dest: 'uploads/' });
app.post('/profile', upload.single('avatar'), (req, res) => {
res.json({ name: req.file.originalname });
});3Verify
Post with the matching field name.
curl -F "avatar=@./photo.jpg" http://localhost:3000/profileConfirmed by github.com
Cause 3 of 4
single() fills req.file, not req.files
1Check
single puts one file in req.file. array and fields put files in req.files; with fields they are grouped by field name.
grep -rn "req\.files\?" --include=*.js . | grep -v node_modules2Fix
Use the middleware that matches what you read.
app.post('/photos', upload.array('photos', 5), (req, res) => {
res.json({ count: req.files.length });
});3Verify
Upload two files at once and see the count.
curl -F "photos=@a.jpg" -F "photos=@b.jpg" http://localhost:3000/photosConfirmed by github.com
Cause 4 of 4
The Multer middleware is not on the route that receives the upload
1Check
Multer runs only where it is added to the route or router. express.json and express.urlencoded do not read multipart bodies.
grep -n "app\.post\|router\.post" routes/*.js server.js2Fix
Put the Multer middleware in the route chain before the handler.
router.post('/upload', upload.single('file'), handler);3Verify
Repeat the failing upload.
curl -F "file=@./photo.jpg" http://localhost:3000/uploadConfirmed by expressjs.com
How do I stop it coming back?
- Set limits.fileSize on every Multer instance; the default has no limit.
- Handle MulterError in your error middleware and return a clear 400.
- Do not set Content-Type yourself when sending FormData from fetch.
- Without options Multer keeps files in memory; use disk or object storage for large files.
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
Express rejects a request body as too large
413 (Request Entity Too Large) returned by nginx in front of the app
A 413 means a body was bigger than a size limit.
3 causes, each with a fixBack 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 fix