Maaz Zindani

Loading the index…

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

Multer rejects an upload because the multipart boundary is missing

ErrorError: Multipart: Boundary not found

Short answer

A multipart body is split by a boundary string that must be announced in the Content-Type header. The error means the header reached the server without a boundary. This happens when a client sets Content-Type: multipart/form-data by hand, or sends a body that is not built as form-data at all.

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

Fix it fast

  1. 1Find out which cause you have

    Send the failing request again and look at the Content-Type header the server really receives. A correct one looks like multipart/form-data; boundary=something.

    app.post('/upload', (req, res, next) => {
      console.log(req.headers['content-type']);
      next();
    }, upload.single('photo'), (req, res) => res.sendStatus(200));
  2. 2Match what you see, then jump to its fix

    1. 1The logged header is exactly multipart/form-data, with no boundary after itThe client set the multipart Content-Type header itselfFix
    2. 2The header has no boundary, and the request was built from a JSON object, raw text or a URL-encoded formThe body is not a multipart body, but the header says it isFix

What does the error look like?

  • Error: Multipart: Boundary not found

Cause 1 of 2

The client set the multipart Content-Type header itself

1Check

The boundary is a parameter of the Content-Type header, and the client picks a fresh value for each request. If you type the header by hand (in a request builder, an axios config or a fetch call), you cannot know the value, so the part after the semicolon is missing.

grep -rn "multipart/form-data" src/ client/ 2>/dev/null

2Fix

Delete the manual Content-Type header and pass a FormData object as the body. The HTTP client then writes the header with its own boundary.

const form = new FormData();
form.append('photo', fileInput.files[0]);
await fetch('/upload', { method: 'POST', body: form });
// no headers: { 'Content-Type': ... } here

3Verify

The logged header now contains boundary=, and Multer fills req.file.

console.log(req.headers['content-type'], req.file);

Confirmed by rfc-editor.org

Did this fix it?

Cause 2 of 2

The body is not a multipart body, but the header says it is

1Check

A multipart body is a series of parts separated by the boundary line. A JSON string or an urlencoded string with a multipart header on top is not that format, so there is nothing to split.

curl -s -o /dev/null -w '%{http_code}\n' -X POST http://localhost:3000/upload -F photo=@./test.jpg

2Fix

Build the request as form-data in your client (in a request builder, choose the form-data body type, not raw), and give the file field the same name that Multer expects.

const multer = require('multer');
const upload = multer({ dest: 'uploads/' });
app.post('/upload', upload.single('photo'), (req, res) => {
  res.json({ file: req.file?.originalname });
});

3Verify

The curl command above returns 200 and the file lands in uploads/.

ls uploads/

Confirmed by rfc-editor.org

Did this fix it?

How do I stop it coming back?

  • Never write the multipart Content-Type header by hand; let the client library create it.
  • Keep one upload helper in the front end, so every upload goes through the same FormData code.
  • Test uploads with a real file from the command line before debugging the browser.

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

Multer rejects the upload with Unexpected field

MulterError: Unexpected file field

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.

4 causes, each with a fix

Next step

Want this handled for good?

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