Maaz Zindani

Loading the index…

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

Uploaded files are missing from the request in Express

Errorreq.files is undefined

Short 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.

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

Fix it fast

  1. 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/profile
  2. 2Match what you see, then jump to its fix

    1. 1req.file and req.files are both undefined, no error, and req.body has only text fieldsThe request is not multipart/form-dataFix
    2. 2error 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. 3req.files is undefined, yet req.file holds the uploadsingle() fills req.file, not req.filesFix
    4. 4req.file is undefined on one route only, while another upload route worksThe Multer middleware is not on the route that receives the uploadFix

What does the error look like?

  • req.files is undefined
  • MulterError: 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 -3

2Fix

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/profile

Confirmed by github.com

Did this fix it?

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_modules

2Fix

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/profile

Confirmed by github.com

Did this fix it?

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_modules

2Fix

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/photos

Confirmed by github.com

Did this fix it?

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.js

2Fix

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/upload

Confirmed by expressjs.com

Did this fix it?

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

Next step

Want this handled for good?

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