# File Uploads with Limits

A form with a file arrives as multipart/form-data, which multer reads in Express, saving the file under a name the server makes and refusing a file that's too big (413) or of the wrong type (400) before it fills the disk.

Freelancer · Node.js · Web Development · Updated November 19, 2026

By Gregor Dzierzon

## After this lesson you can

- Accept one file upload in Express with multer's upload.single, reading req.file and the form's text fields in req.body
- Limit an upload's size and type with multer's limits and fileFilter, answering 413 or 400 with a clear message
- Save an upload under a name the server makes, never the file name the client sent

## Key takeaways

- A form with a file is sent as multipart/form-data, in parts, so express.json() can't read it. multer can.
- upload.single("photo") saves one file from the field photo, puts its details in req.file and the form's text fields in req.body.
- The file name a client sends is never trusted. The server makes the name, such as a randomUUID() and an extension picked from the allowed types.
- limits.fileSize refuses a file that's too big with 413, read "content too large", and fileFilter refuses a type you don't allow with 400.
- Online, uploads belong in storage made for files, such as Amazon S3 or Azure Blob Storage, because a host can wipe its own disk at the next deploy.

Profile pictures, receipts, résumés, homework hand-ins: sooner or later an app takes files. Uploads are also one of the easiest ways to fill a server's disk or overwrite its files, so this lesson covers both halves: accepting files, and refusing the wrong ones.

Snapshot Saturday is moving its entries online: each entrant sends a photo with their name and the photo's title. With `express.json()` in place, the route's `req.body` comes out `undefined`. A photo isn't JSON, and it doesn't arrive as JSON.

## What a file upload looks like

Think of a parcel with a cover letter: several things in one box, each with its own label. A form with a file travels the same way, as **multipart/form-data**: the body is split into parts, each with its own headers. Here's the request as a REST Client `.http` file sends it:

```http
POST http://localhost:3100/entries
Content-Type: multipart/form-data; boundary=SnapshotSaturday

--SnapshotSaturday
Content-Disposition: form-data; name="name"

Grace
--SnapshotSaturday
Content-Disposition: form-data; name="title"

Harbor at dawn
--SnapshotSaturday
Content-Disposition: form-data; name="photo"; filename="sunset.jpg"
Content-Type: image/jpeg

< ./sunset.jpg
--SnapshotSaturday--
```

The **boundary** is the line between parts, and the last one ends with two extra dashes. Each part says its field's `name`; the file's part also says its `filename` and its type, and `< ./sunset.jpg` tells REST Client to send that file's bytes. A browser builds the same thing from a `<form enctype="multipart/form-data">`.

## Accepting one photo with multer

**multer** is the Express middleware that reads these forms. Install it with `npm install multer@2.5.0 --save-exact`, then:

```javascript
import express from "express";
import multer from "multer";

const app = express();
const upload = multer({ dest: "uploads/" });

app.post("/entries", upload.single("photo"), (req, res) => {
  console.log(req.body.name, req.body.title);
  console.log(req.file);
  res.status(201).json({ message: "Thanks for your entry!" });
});

app.listen(3100, () => console.log("Listening on http://localhost:3100"));
```

`upload.single("photo")` accepts one file from the field named `photo` and saves it in `uploads/`. Send the request above, and the terminal shows:

```text
Listening on http://localhost:3100
Grace Harbor at dawn
{
  fieldname: 'photo',
  originalname: 'sunset.jpg',
  encoding: '7bit',
  mimetype: 'image/jpeg',
  path: 'uploads\\1365da442c21b7f521abe70537466907',
  destination: 'uploads/',
  filename: '1365da442c21b7f521abe70537466907',
  size: 929
}
```

The text fields are in `req.body`, and the file's details are in `req.file`: its size in bytes, its type (`mimetype`), the name it was saved under and the name it had on the entrant's computer. (On macOS, `path` reads `uploads/…`.)

## Never trust the file name

`originalname` is whatever the client says, so it's tempting to save the file under it, and it's a mistake. When Ava and Omar both send `IMG_0001.jpg`, the name a phone gives its first photo, the second upload replaces the first: on a test run the folder held one `IMG_0001.jpg`, Omar's 266 bytes, and Ava's 929-byte photo was gone. A name such as `../../server.js` is worse: `..` means "the folder above", so the name climbs out of the uploads folder. That's **path traversal**. multer drops the folders from a name by itself, but other tools, and multer's own `preservePath` option, don't.

The rule: the server makes the name. `randomUUID()` from `node:crypto` gives a new random id every time, and the extension comes from a list of the types you allow, never from the client:

```javascript
const extensions = { "image/jpeg": ".jpg", "image/png": ".png" };

const storage = multer.diskStorage({
  destination: "uploads/",
  filename: (req, file, cb) => {
    cb(null, randomUUID() + extensions[file.mimetype]);
  },
});
```

multer's functions answer through a callback, `cb`: call it with `null` (no error) and the value. `destination` can be a function in the same style when the folder depends on the request.

## Limits on size and type: 413 and 400

Without limits, one entrant could send a 20 GB file and fill the disk. `limits.fileSize` stops reading a file past its size, and `fileFilter` decides about each file before it's saved:

```javascript
const upload = multer({
  storage,
  limits: { fileSize: 5 * 1024 * 1024 },
  fileFilter: (req, file, cb) => {
    if (extensions[file.mimetype]) {
      cb(null, true);
    } else {
      const err = new Error("Only JPEG and PNG photos can enter.");
      err.status = 400;
      cb(err);
    }
  },
});
```

Both send their errors to Express, so an error-handling middleware turns them into answers, each in the course's one error shape, sent with `sendProblem` from *Error Handling and Consistent Error Responses*:

```javascript
app.use((err, req, res, next) => {
  if (err.code === "LIMIT_FILE_SIZE") {
    sendProblem(res, 413, "A photo can be at most 5 MB.");
  } else if (err.status === 400) {
    sendProblem(res, 400, err.message);
  } else {
    console.error(err);
    sendProblem(res, 500, "Something went wrong on our side.");
  }
});
```

The route itself answers 400 when `req.file` is missing. Sending a text file, then a 6 MB file:

```text
HTTP/1.1 400 Bad Request
{"status":400,"title":"Bad Request","detail":"Only JPEG and PNG photos can enter."}

HTTP/1.1 413 Payload Too Large
{"status":413,"title":"Payload Too Large","detail":"A photo can be at most 5 MB."}
```

**413** reads "content too large: I won't take something this big". The HTTP standard now calls it *Content Too Large*; Node still uses its older name, in the status line and in `STATUS_CODES`, so that's the `title` too. multer removes the half-written file, so a refused upload leaves nothing behind. The `mimetype` is the client's word too, so a careful server also checks a file's first bytes: every JPEG starts with the bytes `FF D8 FF`, and every PNG with `89 50 4E 47`.

## Where uploads go when it's online

A folder on your computer is right for learning. Many hosts, Module 6's included, wipe the server's own disk when it restarts or deploys, and two copies of a server don't share one disk. So real apps send each file to storage made for files, such as Amazon S3, Azure Blob Storage or Cloudflare R2, and keep only its name in the database.

## Check yourself

2 questions to try on the lesson page.

## So what

Every upload route needs the same three guards: a size limit, a list of allowed types, and a name the server makes. With those, a file from a stranger is a photo in a folder instead of a full disk or an overwritten one.

## Key terms

- [Multipart form data](https://www.ask-codey.com/glossary/multipart-form-data)
- [multer](https://www.ask-codey.com/glossary/multer)
- [413 Content Too Large](https://www.ask-codey.com/glossary/413-content-too-large)
- [Path Traversal](https://www.ask-codey.com/glossary/path-traversal)

## Related

- [Streams: Big Files a Piece at a Time](https://www.ask-codey.com/lessons/node-streams-big-files)
- [Error Handling and Consistent Error Responses](https://www.ask-codey.com/lessons/node-express-error-handling)
- [The Attacks to Expect: Injection and Mass Assignment](https://www.ask-codey.com/lessons/node-security-common-attacks)

Source: https://www.ask-codey.com/lessons/node-uploads-with-multer
