{"id":17434,"library":"express-fileupload","title":"Express File Upload Middleware","description":"express-fileupload is a straightforward middleware for the Express.js framework, designed to simplify handling multipart/form-data for file uploads. It acts as a wrapper around the `Busboy` parser, exposing uploaded files via `req.files` for easy access. The current stable version is 1.5.2, with minor releases and bug fixes occurring relatively frequently to address issues and introduce small features like custom loggers or hash algorithm options. Key differentiators include its simple API that provides a `mv()` function for relocating uploaded files, direct access to file properties (name, mimetype, size, data buffer), and an option to utilize temporary files on disk instead of memory, which is beneficial for handling large uploads efficiently. The middleware is actively maintained and offers robust handling of file streams.","status":"active","version":"1.5.2","language":"javascript","source_language":"en","source_url":"https://github.com/richardgirges/express-fileupload","tags":["javascript","express","file-upload","upload","forms","multipart","files","busboy","middleware"],"install":[{"cmd":"npm install express-fileupload","lang":"bash","label":"npm"},{"cmd":"yarn add express-fileupload","lang":"bash","label":"yarn"},{"cmd":"pnpm add express-fileupload","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core parsing engine for multipart/form-data requests, express-fileupload is a wrapper around it.","package":"busboy","optional":false}],"imports":[{"note":"While CommonJS `require` still works, modern Express applications often use ESM `import`. Ensure your project is configured for ESM if using `import`.","wrong":"const fileUpload = require('express-fileupload');","symbol":"fileUpload","correct":"import fileUpload from 'express-fileupload';"},{"note":"Configuration options are passed as an object to the `fileUpload` middleware function. Directly assigning properties to the imported module is incorrect.","wrong":"app.use(fileUpload.useTempFiles = true);","symbol":"fileUpload.options","correct":"app.use(fileUpload({ useTempFiles: true, tempFileDir: '/tmp/' }));"},{"note":"The type for an individual uploaded file is `UploadedFile`. This is primarily used for type-checking in TypeScript projects to correctly define `req.files`.","wrong":"import { FileUpload } from 'express-fileupload';","symbol":"UploadedFile","correct":"// In a TypeScript project:\nimport { UploadedFile } from 'express-fileupload';"}],"quickstart":{"code":"import express from 'express';\nimport fileUpload from 'express-fileupload';\nimport path from 'path';\nimport { promises as fs } from 'fs';\n\nconst app = express();\nconst PORT = process.env.PORT || 3000;\nconst UPLOAD_DIR = path.join(process.cwd(), 'uploads');\n\n// Create upload directory if it doesn't exist\nfs.mkdir(UPLOAD_DIR, { recursive: true }).catch(console.error);\n\n// Middleware: Enable file uploads with temporary files\napp.use(fileUpload({\n  useTempFiles: true,\n  tempFileDir: '/tmp/', // Ensure this directory exists and is writable\n  limits: { fileSize: 50 * 1024 * 1024 } // 50MB limit\n}));\n\napp.post('/upload', async (req, res) => {\n  if (!req.files || Object.keys(req.files).length === 0) {\n    return res.status(400).send('No files were uploaded.');\n  }\n\n  // 'foo' is the name of the input field in the form\n  const uploadedFile = req.files.foo;\n\n  // Check if uploadedFile is an array (multiple files with same name attribute)\n  // For simplicity, assume single file upload with 'foo' name.\n  if (Array.isArray(uploadedFile)) {\n    return res.status(400).send('Multiple files for a single input field not supported in this example.');\n  }\n\n  const uploadPath = path.join(UPLOAD_DIR, uploadedFile.name);\n\n  try {\n    await uploadedFile.mv(uploadPath);\n    res.send(`File uploaded to ${uploadPath}`);\n  } catch (err) {\n    console.error(err);\n    res.status(500).send(err.message);\n  }\n});\n\napp.get('/', (req, res) => {\n  res.send(`\n    <h1>Upload a File</h1>\n    <form action=\"/upload\" method=\"post\" enctype=\"multipart/form-data\">\n      <input type=\"file\" name=\"foo\" />\n      <input type=\"submit\" value=\"Upload\" />\n    </form>\n  `);\n});\n\napp.listen(PORT, () => {\n  console.log(`Server listening on port ${PORT}`);\n  console.log(`Uploads will be saved to ${UPLOAD_DIR}`);\n});","lang":"javascript","description":"This quickstart demonstrates a basic Express server configured with `express-fileupload` to handle file uploads. It shows how to initialize the middleware with options like temporary file usage and size limits, how to access uploaded files via `req.files`, and how to move them to a permanent location using the `mv()` method. A simple HTML form is also provided for testing the upload functionality."},"warnings":[{"fix":"Upgrade your Node.js environment to version 12.0.0 or newer to ensure compatibility and receive security updates.","message":"Node.js versions prior to 12 are no longer supported since v1.3.1. Applications running on older Node.js runtimes will encounter errors or unexpected behavior.","severity":"breaking","affected_versions":">=1.3.1"},{"fix":"Developers should explicitly verify the expected `md5` behavior for their specific `express-fileupload` version. If you relied on `md5` being a function between v1.0.0 and v1.1.1, you must update your code. For versions 1.5.1+, consider using the `hashAlgorithm` option for specific hashing needs.","message":"The behavior of the `md5` property on uploaded file objects has changed multiple times across versions. It was a checksum (before v1.0.0), then a function (v1.0.0-1.1.1), then reverted to a checksum (v1.1.1-1.5.1), and from v1.5.1, it's still a checksum but generated with a configurable `hashAlgorithm` while the property name remains `md5` for backward compatibility.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Upgrade to `express-fileupload` v1.5.2 or newer to receive the fix for temporary file name conflicts. This ensures unique temporary file identification.","message":"Older versions (pre-1.5.2) could experience possible conflicts for temporary file names, leading to data corruption or incorrect file handling, especially under high concurrency.","severity":"gotcha","affected_versions":"<1.5.2"},{"fix":"Immediately upgrade to `express-fileupload` v1.3.1 or later to mitigate the prototype pollution vulnerability. Regularly scan dependencies for known CVEs.","message":"Prototype pollution vulnerability was fixed in v1.3.1. This type of vulnerability could allow an attacker to inject arbitrary properties into object prototypes, potentially leading to remote code execution or denial of service.","severity":"gotcha","affected_versions":"<1.3.1"},{"fix":"Upgrade to `express-fileupload` v1.4.1 or newer to correctly process file names containing special characters.","message":"Handling of file names with special characters (e.g., non-ASCII) was problematic in versions prior to v1.4.1, potentially causing upload failures or incorrect file paths.","severity":"gotcha","affected_versions":"<1.4.1"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Upgrade `express-fileupload` to v1.4.2 or newer. This version specifically addresses the `TypeError: file.destroy is not a function` error.","cause":"An issue in older versions where the `file.destroy` method was incorrectly implemented or missing for certain scenarios, preventing proper cleanup of temporary file streams.","error":"TypeError: file.destroy is not a function"},{"fix":"Update `express-fileupload` to v1.4.3 or a later version. This release includes a fix for the `TypeError` related to `isEligibleRequest.js`.","cause":"This error typically occurred in older versions when the middleware attempted to check request headers or methods on an undefined object, often due to malformed requests or specific edge cases.","error":"TypeError - Cannot read properties of undefined (reading 'includes') in lib/isEligibleRequest.js"},{"fix":"Upgrade `express-fileupload` to v1.2.1 or newer. This version includes updates to better handle promise rejections and prevent unhandled promise warnings.","cause":"In versions prior to v1.2.1, certain asynchronous operations within the middleware, particularly related to limit handlers or file processing, might not have properly caught or handled promise rejections, leading to unhandled promise warnings in Node.js.","error":"Unhandled promise rejection warning"},{"fix":"Ensure `express-fileupload` is updated to at least v1.4.2, which included stricter request checks and improved handling of abortions on limit exceeding (preventing `next()` from being called after abortion). Implement client-side retry logic and server-side logging for aborted requests.","cause":"While not a direct error message *from* express-fileupload, users might encounter this in their server logs when a client prematurely disconnects during a large upload, or when file size limits are exceeded and the connection is terminated by the server without proper cleanup or error propagation in older versions.","error":"Error: Request aborted"}],"ecosystem":"npm","meta_description":null}