Multer Error Handling: Fix Common Upload Errors

File uploads can fail for many reasons such as invalid file types, size limits, or unexpected input. Multer provides built-in mechanisms to detect and handle these errors effectively.

How does Multer handle errors?

Multer passes errors to Express using the standard middleware error flow.

• If an error occurs, it is passed to the next middleware
• You can catch it using error-handling middleware
• Errors can be generic or specific to Multer

What are common Multer errors?

Some common errors you may encounter:

• LIMIT_FILE_SIZE → File exceeds size limit
• LIMIT_FILE_COUNT → Too many files uploaded
• LIMIT_UNEXPECTED_FILE → Unexpected field name
• LIMIT_FIELD_COUNT → Too many non-file fields

These errors are instances of MulterError.

How to catch Multer errors in Express?

You can catch errors by wrapping the upload middleware manually.

Example:

const multer = require("multer");
const upload = multer({ limits: { fileSize: 1024 * 1024 } }); // 1MB

app.post("/upload", (req, res) => {
  upload.single("file")(req, res, function (err) {
    if (err) {
      return res.status(400).json({ error: err.message });
    }

    res.send("File uploaded successfully");
  });
});

What is MulterError?

MulterError is a class used by Multer to represent upload-specific errors.

Example:

const multer = require("multer");

app.post("/upload", (req, res) => {
  upload.single("file")(req, res, function (err) {
    if (err instanceof multer.MulterError) {
      return res.status(400).json({
        type: "MulterError",
        message: err.message,
      });
    } else if (err) {
      return res.status(500).json({
        type: "UnknownError",
        message: err.message,
      });
    }

    res.send("Upload successful");
  });
});

How to handle file upload failures gracefully?

To handle failures properly:

• Validate files before upload (using fileFilter)
• Set limits (file size, count)
• Provide meaningful error messages
• Avoid crashing the server

Example with graceful handling:

const upload = multer({
  limits: { fileSize: 1024 * 1024 }, // 1MB
});

app.post("/upload", (req, res) => {
  upload.single("file")(req, res, function (err) {
    if (err) {
      return res.status(400).json({
        success: false,
        message: err.message,
      });
    }

    if (!req.file) {
      return res.status(400).json({
        success: false,
        message: "No file uploaded",
      });
    }

    res.json({
      success: true,
      message: "File uploaded successfully",
      file: req.file,
    });
  });
});

Complete Example

const express = require("express");
const multer = require("multer");

const app = express();

const upload = multer({
  limits: { fileSize: 1024 * 1024 },
});

app.post("/upload", (req, res) => {
  upload.single("file")(req, res, function (err) {
    if (err instanceof multer.MulterError) {
      return res.status(400).send("Multer error: " + err.message);
    } else if (err) {
      return res.status(500).send("Unknown error: " + err.message);
    }

    if (!req.file) {
      return res.status(400).send("No file uploaded");
    }

    res.send("File uploaded successfully");
  });
});

app.listen(3000, () => {
  console.log("Server running on port 3000");
});

Key Takeaways

• Multer uses Express error-handling flow
• Common errors include file size, count, and unexpected fields
• Use MulterError to identify specific issues
• Always handle errors to avoid server crashes