File Upload in Node.js with Multer

A user uploads a profile photo. Your server crashes because the image is 50MB. Another user uploads profile.html and your server runs it. File upload is the most common attack vector in any Node.js API, and Multer handles the basic mechanics but leaves security entirely up to you. This article covers the complete file upload pipeline: accepting uploads with Multer, validating file types and sizes, streaming directly to S3, virus scanning, and serving uploaded files securely.

Why Multer? The Problem with Raw File Handling

Handling file uploads in Node.js with raw req.on('data') is error-prone: you must manually parse multipart boundaries, handle backpressure, and manage disk writes. Multer abstracts this complexity by wrapping the popular busboy parser and providing a middleware API. It handles MIME type detection, file size limits, and storage configuration. Without Multer, you risk memory exhaustion from buffering large files, corrupted uploads from incomplete boundary parsing, and security holes from unrestricted file types. Multer is the de facto standard for Express apps because it's battle-tested and production-ready. However, it's not a magic bullet — you still need to validate files after Multer processes them.

const http = require('http');
const fs = require('fs');

const server = http.createServer((req, res) => {
  if (req.method === 'POST' && req.url === '/upload') {
    const chunks = [];
    req.on('data', chunk => chunks.push(chunk));
    req.on('end', () => {
      const buffer = Buffer.concat(chunks);
      // Manual multipart parsing is fragile and not shown here
      fs.writeFileSync('upload.bin', buffer);
      res.end('Uploaded');
    });
  }
});
server.listen(3000);

Setting Up Multer: Basic Configuration

Install Multer with npm install multer. The core is the multer() function, which returns a middleware. You configure it with a dest or storage option. The simplest setup uses dest: 'uploads/' to save files to a directory with auto-generated filenames. Multer adds a file object to req.file (for single uploads) or req.files (for multiple). The middleware must be placed before your route handler. Always specify limits to prevent abuse: fileSize in bytes, files max count. Without limits, a malicious client can upload unlimited data and fill your disk. Also set fileFilter to restrict MIME types — never trust the client's Content-Type alone.

const express = require('express');
const multer = require('multer');
const path = require('path');

const app = express();

const upload = multer({
  dest: 'uploads/',
  limits: {
    fileSize: 5 * 1024 * 1024, // 5 MB
    files: 1
  },
  fileFilter: (req, file, cb) => {
    const allowedTypes = /jpeg|jpg|png|gif/;
    const extname = allowedTypes.test(path.extname(file.originalname).toLowerCase());
    const mimetype = allowedTypes.test(file.mimetype);
    if (mimetype && extname) {
      return cb(null, true);
    } else {
      cb(new Error('Only images are allowed'));
    }
  }
});

app.post('/upload', upload.single('avatar'), (req, res) => {
  res.json({ file: req.file });
});

app.listen(3000);

Custom Storage: DiskStorage for Production

The default dest option uses multer.diskStorage() under the hood, but you can customize it to control filenames and destination paths. Use diskStorage when you need to preserve original filenames, add timestamps, or organize files into subdirectories. The destination function receives (req, file, cb) — call cb(null, 'path'). The filename function receives (req, file, cb) — call cb(null, 'unique-name.ext'). Always generate unique filenames to avoid collisions. A common pattern is Date.now() + '-' + randomHex + ext. Never use the original filename directly — it can contain path traversal characters like ../ that overwrite system files.

const multer = require('multer');
const path = require('path');
const crypto = require('crypto');

const storage = multer.diskStorage({
  destination: (req, file, cb) => {
    cb(null, 'uploads/');
  },
  filename: (req, file, cb) => {
    const ext = path.extname(file.originalname);
    const uniqueName = crypto.randomBytes(16).toString('hex') + ext;
    cb(null, uniqueName);
  }
});

const upload = multer({ storage });

app.post('/upload', upload.single('file'), (req, res) => {
  res.json({ filename: req.file.filename });
});

Handling Multiple Files: Arrays and Fields

Multer supports multiple file uploads via upload.array('fieldname', maxCount) for multiple files with the same field name, or upload.fields([{ name: 'avatar', maxCount: 1 }, { name: 'gallery', maxCount: 8 }]) for different fields. The files are available in req.files as an array or object. For array, req.files is an array of file objects. For fields, req.files is an object keyed by field name. Always set maxCount to prevent abuse. When using array, the client must send multiple files with the same field name. For mixed uploads (e.g., avatar + multiple gallery images), use fields.

const upload = multer({ dest: 'uploads/' });

// Single field with multiple files
app.post('/upload-multiple', upload.array('photos', 5), (req, res) => {
  res.json({ files: req.files });
});

// Multiple fields
app.post('/upload-mixed', upload.fields([
  { name: 'avatar', maxCount: 1 },
  { name: 'gallery', maxCount: 8 }
]), (req, res) => {
  res.json({
    avatar: req.files['avatar'][0],
    gallery: req.files['gallery']
  });
});

Error Handling: Multer Errors and Custom Middleware

Multer errors (e.g., file too large, wrong file type, too many files) throw MulterError instances. You must catch them in Express error-handling middleware. The error object has a code property: LIMIT_FILE_SIZE, LIMIT_FILE_COUNT, LIMIT_UNEXPECTED_FILE, etc. Also, custom errors from fileFilter are passed via cb(new Error('...')). Wrap the upload middleware in a try-catch or use Express's error handler. Without proper handling, uncaught errors crash the process. Always return a user-friendly message and log the error server-side.

const multer = require('multer');
const upload = multer({ dest: 'uploads/', limits: { fileSize: 1000000 } });

app.post('/upload', (req, res, next) => {
  upload.single('file')(req, res, (err) => {
    if (err instanceof multer.MulterError) {
      // A Multer error occurred when uploading.
      if (err.code === 'LIMIT_FILE_SIZE') {
        return res.status(413).json({ error: 'File too large' });
      }
      return res.status(400).json({ error: err.message });
    } else if (err) {
      // An unknown error occurred.
      return res.status(500).json({ error: 'Upload failed' });
    }
    // Everything went fine.
    res.json({ file: req.file });
  });
});

app.use((err, req, res, next) => {
  console.error(err.stack);
  res.status(500).send('Something broke!');
});

Validation Beyond Multer: File Content and Security

Multer's fileFilter only checks MIME type and extension, which are easily spoofed. For real security, validate file content using magic bytes. Libraries like file-type read the first few bytes to determine the true type. Also, scan for malware using ClamAV or a cloud service. Never execute uploaded files or serve them from the same domain without sanitization. Store files outside the web root or use a separate CDN. Additionally, validate file dimensions for images (e.g., using sharp or gm) to prevent denial-of-service via decompression bombs.

const FileType = require('file-type');
const fs = require('fs');

app.post('/upload', upload.single('file'), async (req, res) => {
  if (!req.file) return res.status(400).json({ error: 'No file' });

  // Read first 4100 bytes for magic bytes detection
  const buffer = fs.readFileSync(req.file.path, { start: 0, end: 4100 });
  const type = await FileType.fromBuffer(buffer);

  if (!type || !['image/jpeg', 'image/png', 'image/gif'].includes(type.mime)) {
    // Delete the file
    fs.unlinkSync(req.file.path);
    return res.status(400).json({ error: 'Invalid file type' });
  }

  // Additional validation: image dimensions
  const sharp = require('sharp');
  const metadata = await sharp(req.file.path).metadata();
  if (metadata.width > 2000 || metadata.height > 2000) {
    fs.unlinkSync(req.file.path);
    return res.status(400).json({ error: 'Image dimensions too large' });
  }

  res.json({ file: req.file });
});

Serving Uploaded Files Securely

Never serve uploaded files directly from the upload directory using express.static without restrictions. An attacker could upload a malicious script and execute it. Instead, serve files through a route that validates authentication and authorization. Use res.sendFile with an absolute path, and sanitize the filename parameter to prevent directory traversal. Set appropriate Content-Type headers and Content-Disposition to force download if needed. Also, consider using a CDN or cloud storage (S3, GCS) for serving files — this offloads traffic and adds a security layer.

const path = require('path');
const fs = require('fs');

app.get('/files/:filename', (req, res) => {
  const filename = req.params.filename;
  // Prevent directory traversal
  const safePath = path.normalize(filename).replace(/^(\..*?\/)/, '');
  const filePath = path.join(__dirname, 'uploads', safePath);

  // Check file exists
  if (!fs.existsSync(filePath)) {
    return res.status(404).json({ error: 'File not found' });
  }

  // Set headers
  res.setHeader('Content-Type', 'application/octet-stream');
  res.setHeader('Content-Disposition', `attachment; filename="${path.basename(filePath)}"`);
  res.sendFile(filePath);
});

Production Considerations: Scaling and Storage

In production, storing files on the local disk is not scalable. Use cloud storage like AWS S3, Google Cloud Storage, or Azure Blob Storage. Multer has a multer-s3 package that streams directly to S3. This avoids disk I/O bottlenecks and provides durability. Also, consider using a reverse proxy (Nginx) to handle file uploads before they reach Node.js — Nginx can buffer to disk and limit upload size more efficiently. Implement rate limiting per user to prevent abuse. Finally, always have a cleanup job for incomplete or abandoned uploads.

const multer = require('multer');
const multerS3 = require('multer-s3');
const { S3Client } = require('@aws-sdk/client-s3');

const s3 = new S3Client({ region: 'us-east-1' });

const upload = multer({
  storage: multerS3({
    s3: s3,
    bucket: 'my-bucket',
    metadata: (req, file, cb) => {
      cb(null, { fieldName: file.fieldname });
    },
    key: (req, file, cb) => {
      const ext = path.extname(file.originalname);
      const uniqueName = Date.now().toString() + '-' + crypto.randomBytes(8).toString('hex') + ext;
      cb(null, uniqueName);
    }
  }),
  limits: { fileSize: 10 * 1024 * 1024 }
});

app.post('/upload', upload.single('file'), (req, res) => {
  res.json({ location: req.file.location });
});

Testing File Uploads: Integration and Unit Tests

Testing file uploads requires simulating multipart requests. Use supertest with attach() to send files. For unit tests, mock Multer's middleware to avoid actual disk I/O. Integration tests should use a temporary directory and clean up after. Test error cases: file too large, wrong type, missing field, and concurrent uploads. Also test that files are properly deleted on validation failure. Without tests, regressions can slip in — e.g., a change in Multer version may break your custom storage.

const request = require('supertest');
const app = require('./app');
const path = require('path');

describe('File Upload', () => {
  it('should upload a valid image', async () => {
    const res = await request(app)
      .post('/upload')
      .attach('avatar', path.join(__dirname, 'test-image.jpg'));
    expect(res.status).toBe(200);
    expect(res.body.file).toHaveProperty('filename');
  });

  it('should reject oversized file', async () => {
    const res = await request(app)
      .post('/upload')
      .attach('avatar', path.join(__dirname, 'large-file.jpg'));
    expect(res.status).toBe(413);
  });

  it('should reject invalid file type', async () => {
    const res = await request(app)
      .post('/upload')
      .attach('avatar', path.join(__dirname, 'malware.exe'));
    expect(res.status).toBe(400);
  });
});

Common Pitfalls and How to Avoid Them

1. Missing enctype: The HTML form must have enctype="multipart/form-data". Without it, Multer receives no files. 2. Field name mismatch: The field name in upload.single('field') must match the client's field name exactly. 3. Not handling MulterError: Uncaught errors crash the server. 4. Trusting file extensions: Always validate content. 5. Serving uploads directly: Exposes your server to code execution. 6. No rate limiting: Attackers can flood your upload endpoint. 7. Ignoring cleanup: Abandoned uploads fill disk space. Use a cron job to delete files older than a threshold.

<form action="/upload" method="POST" enctype="multipart/form-data">
  <input type="file" name="avatar" />
  <button type="submit">Upload</button>
</form>

Performance Optimization: Streaming and Buffering

Multer streams files to disk by default, which is memory-efficient. However, if you use memoryStorage, files are buffered in RAM — only use for small files (e.g., < 5MB). For large files, always use diskStorage or cloud storage. To further optimize, use a reverse proxy like Nginx to handle uploads before they reach Node.js. Nginx can buffer to disk and limit upload size, freeing Node.js to handle other requests. Also, consider using busboy directly if you need more control over streaming. Monitor disk I/O — if your server is I/O bound, move to cloud storage.

server {
    listen 80;
    client_max_body_size 10M;

    location /upload {
        proxy_pass http://node_app;
        proxy_request_buffering on;
        client_body_buffer_size 128k;
        client_body_temp_path /tmp/nginx-uploads;
    }
}

Alternative Approaches: When Not to Use Multer

Multer is great for Express apps, but not always the best choice. For high-throughput scenarios, consider using a dedicated file upload service like Uploadcare or Transloadit. For serverless (AWS Lambda), use API Gateway's binary support and S3 presigned URLs. For GraphQL, use the graphql-upload package. Multer is synchronous middleware — it blocks the request until the upload is complete. If you need to process uploads asynchronously (e.g., generate thumbnails), offload to a queue (Bull, RabbitMQ) after Multer saves the file.

const Queue = require('bull');
const uploadQueue = new Queue('file processing');

app.post('/upload', upload.single('file'), async (req, res) => {
  const job = await uploadQueue.add({ filePath: req.file.path });
  res.json({ jobId: job.id });
});

// Worker process
uploadQueue.process(async (job) => {
  const { filePath } = job.data;
  // Process file (e.g., generate thumbnail)
  await sharp(filePath).resize(200, 200).toFile(filePath + '_thumb.jpg');
});

Complete End-to-End Example: HTML Form + Server

To see Multer in action, here's a minimal but complete example. The HTML form uses enctype="multipart/form-data" and a file input. The server uses Multer with dest: 'uploads/' for simplicity. This example handles a single file upload and returns a JSON response with file metadata. In production, replace dest with a custom storage engine and add validation.

<form action="/upload" method="post" enctype="multipart/form-data">
  <input type="file" name="avatar" />
  <button type="submit">Upload</button>
</form>

Multer fileFilter: Type Validation

Multer's fileFilter option lets you validate file types before storage. The callback receives req, file, and a cb function. Call cb(null, true) to accept or cb(null, false) to reject. You can also pass an error to cb to trigger Multer's error handling. Common use cases: allow only images (JPEG, PNG, GIF) or PDFs. Always check the MIME type, not just the extension, as clients can spoof extensions. Example: filter for images only.

const multer = require('multer');

const upload = multer({
  dest: 'uploads/',
  fileFilter: (req, file, cb) => {
    const allowedTypes = ['image/jpeg', 'image/png', 'image/gif'];
    if (allowedTypes.includes(file.mimetype)) {
      cb(null, true);
    } else {
      cb(new Error('Only images are allowed'), false);
    }
  }
});

Multer limits: Size and Count

Multer's limits option controls file size, number of files, and field sizes. Set fileSize in bytes (e.g., 1MB = 1024*1024). Use files to limit the number of files per request. These limits prevent resource exhaustion. If exceeded, Multer throws a MulterError with code LIMIT_FILE_SIZE or LIMIT_UNEXPECTED_FILE. Handle these in your error middleware. Example: limit to 5 files, each max 2MB.

const upload = multer({
  dest: 'uploads/',
  limits: {
    fileSize: 2 * 1024 * 1024, // 2 MB
    files: 5
  }
});

// Error handling middleware
app.use((err, req, res, next) => {
  if (err instanceof multer.MulterError) {
    if (err.code === 'LIMIT_FILE_SIZE') {
      return res.status(413).json({ error: 'File too large' });
    }
    if (err.code === 'LIMIT_FILE_COUNT') {
      return res.status(400).json({ error: 'Too many files' });
    }
  }
  next(err);
});

MemoryStorage vs DiskStorage: Tradeoffs

Multer offers two built-in storage engines: MemoryStorage and DiskStorage. MemoryStorage stores files as Buffer objects in memory, useful for small files or when you need to process them immediately (e.g., upload to cloud storage). DiskStorage writes files to disk, giving control over filename and path. Tradeoffs: MemoryStorage uses RAM and is not suitable for large files; DiskStorage uses disk I/O but persists files. Choose based on your workflow: if you need to forward files to another service, MemoryStorage avoids temporary files. If you need to serve files later, DiskStorage is simpler.

// MemoryStorage
const storage = multer.memoryStorage();
const upload = multer({ storage });

// DiskStorage
const storage = multer.diskStorage({
  destination: (req, file, cb) => cb(null, 'uploads/'),
  filename: (req, file, cb) => cb(null, Date.now() + '-' + file.originalname)
});
const upload = multer({ storage });