Skip to main content

How to Resolve the "ReferenceError: FormData is not defined" Error in Node.js in JavaScript

When working with HTTP requests, you may encounter the error ReferenceError: FormData is not defined. This error occurs when you attempt to use the FormData API—a standard feature in web browsers—within a Node.js environment, where it is not a built-in global.

This guide will explain why this error happens and provide the standard, modern solution for working with multipart/form-data in Node.js.

The Core Problem: Browser API vs. Node.js Environment​

The FormData interface is a Web API, meaning it is provided by browsers as part of the window object. It is designed to construct a set of key-value pairs representing form fields and their values, which can then be easily sent using fetch or XMLHttpRequest.

Node.js, however, is a server-side runtime. It does not have a browser environment or a window object, so FormData is not available as a built-in global. When you try to call new FormData(), Node.js cannot find the constructor and throws a ReferenceError.

The Solution (for Node.js): Use the form-data Package​

To replicate the FormData functionality in Node.js, the standard and most common solution is to use the form-data npm package. It is a polyfill that implements the FormData interface, allowing you to build multipart/form-data streams for file uploads and other complex requests.

The steps:

  1. Install the package: 
    npm install form-data
  2. Import and use it: You can then import the FormData class and use it just like you would in the browser.

Example of code with problems:

// ⛔️ This will throw "FormData is not defined" in Node.js
const form = new FormData();
form.append('field', 'my value');

The solution:

// Import the package
import FormData from 'form-data';
import fs from 'fs';

// ✅ This now works correctly
const form = new FormData();
form.append('field', 'my value');
form.append('file', fs.createReadStream('./my-avatar.png'));

// You can now use this `form` object with libraries like Axios or node-fetch.
// For example, with Axios:
// await axios.post('https://example.com/upload', form, { headers: form.getHeaders() });
note

If you are using CommonJS (require), the import statement is slightly different:

const FormData = require('form-data');

A Note on URLSearchParams (and Why It's Different)​

You might see URLSearchParams suggested as an alternative. While it is available as a global in Node.js and is used for sending form data, it serves a different purpose.

Featureform-data (polyfill for FormData)URLSearchParams
Content-Typemultipart/form-dataapplication/x-www-form-urlencoded
Use CaseUploading files, complex data.Simple key-value text data (like a standard HTML form submission).
File Uploads?YesNo
note

Rule of Thumb:

  • If you need to upload a file or construct a multipart/form-data request, you must use the form-data package.
  • If you only need to send simple key-value pairs (like from a login form without a file), URLSearchParams is a valid, built-in choice.

The Browser Case: A Simple Typo​

If you encounter the "FormData is not defined" error while running code in a web browser, it is almost certainly a simple typo. The constructor is case-sensitive.

// ⛔️ Incorrect: lowercase "d"
const form = new formdata(); 

// ✅ Correct: uppercase "D"
const form = new FormData();

Conclusion​

The FormData is not defined error is a clear indicator of an environment mismatch.

  • If the error occurs in Node.js, it's because FormData is a browser API. The solution is to install and use the form-data npm package.
  • If the error occurs in the browser, it is almost certainly a case-sensitivity typo. Ensure you are using new FormData().

By understanding the context, you can easily solve this common error.

Table of Contents