coderain blog

How to Fix Axios Error: 'Data after transformation must be a string, an ArrayBuffer, a Buffer, or a Stream' in POST Requests with FormData

If you’ve worked with Axios to send POST requests containing FormData (e.g., for file uploads or form submissions with mixed data types), you may have encountered the frustrating error: "Data after transformation must be a string, an ArrayBuffer, a Buffer, or a Stream". This error typically arises from misconfigurations in how Axios processes and transforms data before sending it to the server.

In this blog, we’ll demystify this error, explore its root causes, and provide step-by-step solutions with practical examples to help you resolve it quickly. By the end, you’ll understand how to properly structure Axios requests with FormData to avoid this common pitfall.

2026-01

Table of Contents#

  1. Understanding the Error
  2. Common Causes of the Error
  3. Step-by-Step Solutions
  4. Practical Examples: Before and After
  5. Prevention Tips: Best Practices
  6. Conclusion
  7. References

Understanding the Error#

The error message "Data after transformation must be a string, an ArrayBuffer, a Buffer, or a Stream" occurs when Axios’s data transformation process produces an invalid data type for the request body.

By default, Axios applies transformations to request data (via transformRequest) for POST, PUT, and PATCH requests. For example, if you send a JavaScript object, Axios automatically converts it to a JSON string using JSON.stringify(). However, FormData—a special object used to construct key-value pairs for multipart form data (e.g., files, text fields)—is not a valid input for JSON.stringify(). When Axios tries to transform FormData using its default logic, it results in an invalid format (e.g., the string "[object FormData]"), triggering the error.

Common Causes of the Error#

To fix the error, we first need to identify why Axios is producing invalid transformed data. Here are the most frequent culprits:

1. Axios’s Default Data Transformation#

Axios’s default transformRequest for POST requests is:

transformRequest: [function (data) {
  // Do whatever you want to transform the data
  return JSON.stringify(data);
}]

When you pass FormData as data, JSON.stringify(FormData) returns "[object FormData]"—a string, but not a valid format for multipart/form-data requests. This invalid string causes the error.

2. Manually Setting the Content-Type Header#

Developers often try to "help" by manually setting the Content-Type header to multipart/form-data for FormData requests. However:

  • Browsers automatically set the Content-Type for FormData requests to multipart/form-data; boundary=----WebKitFormBoundary... (the boundary is a unique string separating form fields, critical for the server to parse the data).
  • Manually setting Content-Type: multipart/form-data without the boundary results in an invalid request, and Axios may still attempt to transform the data.

3. Mixing FormData with Other Data Types#

If you accidentally append non-FormData data (e.g., a JavaScript object) to the request body, Axios will apply its default transformation to the entire payload, leading to invalid data.

4. Outdated Axios Versions#

Older versions of Axios (pre-v0.21.0) had bugs related to FormData handling, such as improper transformation logic or header management.

Step-by-Step Solutions#

Let’s address each cause with actionable fixes:

Solution 1: Disable Axios’s Default Data Transformation#

To prevent Axios from transforming FormData, override transformRequest to return the data as-is. Set transformRequest: () => data in the Axios config. This tells Axios not to modify the FormData object.

Solution 2: Never Manually Set Content-Type for FormData#

Remove any explicit Content-Type header from your Axios request. Let the browser automatically generate the multipart/form-data header with the required boundary.

Solution 3: Validate FormData Construction#

Ensure you’re correctly creating and populating the FormData object. Use FormData.append() to add fields/files, and avoid mixing data types.

Solution 4: Update Axios to the Latest Version#

If you’re using an older Axios version, upgrade to v0.21.0 or later to benefit from bug fixes related to FormData handling.

Practical Examples: Before and After#

Let’s walk through a common "broken" example and fix it step-by-step.

Bad Example (Causes the Error)#

// ❌ Broken code that triggers the error
import axios from 'axios';
 
const submitForm = async () => {
  const formData = new FormData();
  formData.append('username', 'john_doe');
  formData.append('avatar', fileInput.files[0]); // Assume fileInput is an <input type="file">
 
  try {
    await axios.post('/api/upload', formData, {
      headers: {
        'Content-Type': 'multipart/form-data', // ❌ Manually setting Content-Type (no boundary)
      },
      // ❌ Axios uses default transformRequest (tries to stringify FormData)
    });
  } catch (error) {
    console.error('Error:', error.message); // "Data after transformation must be a string..."
  }
};

Fixed Example (Resolves the Error)#

// ✅ Fixed code
import axios from 'axios';
 
const submitForm = async () => {
  const formData = new FormData();
  formData.append('username', 'john_doe');
  formData.append('avatar', fileInput.files[0]);
 
  try {
    await axios.post('/api/upload', formData, {
      // ✅ Disable transformation: return FormData as-is
      transformRequest: () => data, 
      // ✅ Remove manual Content-Type header (browser auto-generates it)
      headers: {
        // 'Content-Type': 'multipart/form-data' ❌ Remove this line
      },
    });
    console.log('Upload successful!');
  } catch (error) {
    console.error('Error:', error.message);
  }
};

Key Fixes in the Example#

  • transformRequest: () => data disables Axios’s default JSON stringification.
  • No manual Content-Type header: the browser sets multipart/form-data; boundary=... automatically.

Node.js Note#

In Node.js (e.g., server-side requests), use the form-data library instead of the browser’s FormData. The fix is similar, but you’ll need to extract headers from the form-data instance:

import axios from 'axios';
import FormData from 'form-data';
 
const formData = new FormData();
formData.append('field', 'value');
 
await axios.post('/api/upload', formData, {
  headers: formData.getHeaders(), // ✅ Let form-data generate headers with boundary
  transformRequest: () => formData, // ✅ Disable Axios transformation
});

Prevention Tips: Best Practices#

To avoid this error in future projects, follow these best practices:

1. Always Disable transformRequest for FormData#

Make it a habit to set transformRequest: () => data when sending FormData with Axios.

2. Never Manually Set Content-Type for FormData#

Rely on the browser (or form-data library in Node.js) to generate the Content-Type header with the boundary.

3. Validate FormData Before Sending#

Log the FormData entries to ensure it’s populated correctly:

// Debug FormData contents
for (const [key, value] of formData.entries()) {
  console.log(`${key}:`, value);
}

4. Use Browser DevTools to Inspect Requests#

Check the "Network" tab in Chrome/Firefox DevTools to verify:

  • The Content-Type header is multipart/form-data; boundary=....
  • The request payload shows form fields/files correctly.

5. Keep Axios Updated#

Run npm update axios to stay on the latest version and avoid known bugs.

Conclusion#

The "Data after transformation must be a string..." error in Axios POST requests with FormData is almost always caused by two issues:

  1. Axios’s default data transformation (JSON stringification) corrupting FormData.
  2. Manually setting an invalid Content-Type header.

By disabling Axios’s transformRequest and letting the browser handle the Content-Type header, you can resolve the error quickly. Use the practical examples above to validate your implementation, and follow the prevention tips to avoid recurrence.

References#