axios/axios · error · AxiosError

ERR_FORM_DATA_DEPTH_EXCEEDED

ERR_FORM_DATA_DEPTH_EXCEEDED

Error message

FormData field is too deeply nested (${index} levels). Max depth: ${MAX_DEPTH}

What it means

Thrown while converting multipart FormData back into a JSON object (lib/helpers/formDataToJSON.js:9-15): field names like `a[b][c]` are parsed into property paths, and if a single field nests deeper than DEFAULT_FORM_DATA_MAX_DEPTH the conversion aborts with ERR_FORM_DATA_DEPTH_EXCEEDED. The cap prevents pathological or malicious field names from building enormous nested objects (resource-exhaustion / abuse guard).

Source

Thrown at lib/helpers/formDataToJSON.js:11

'use strict';

import utils from '../utils.js';
import AxiosError from '../core/AxiosError.js';
import { DEFAULT_FORM_DATA_MAX_DEPTH } from './toFormData.js';

const MAX_DEPTH = DEFAULT_FORM_DATA_MAX_DEPTH;

function throwIfDepthExceeded(index) {
  if (index > MAX_DEPTH) {
    throw new AxiosError(
      'FormData field is too deeply nested (' + index + ' levels). Max depth: ' + MAX_DEPTH,
      AxiosError.ERR_FORM_DATA_DEPTH_EXCEEDED
    );
  }
}

/**
 * It takes a string like `foo[x][y][z]` and returns an array like `['foo', 'x', 'y', 'z']
 *
 * @param {string} name - The name of the property to get.
 *
 * @returns An array of strings.
 */
function parsePropPath(name) {
  // foo[x][y][z] -> ['foo', 'x', 'y', 'z']
  // foo.x.y.z    -> ['foo', 'x', 'y', 'z']
  // A path is split on `.` and on `[...]` groups. A segment — whether written
  // in dot notation or captured inside brackets — may contain any character

View on GitHub (pinned to c3f553c740)

Solutions

1. Flatten the data model — deeply bracket-nested field names are usually a sign the payload should be sent as JSON (`Content-Type: application/json`) instead of multipart.
2. Send the nested part as a JSON string field (`form.append('payload', JSON.stringify(obj))`) and parse it server-side.
3. Restructure field names to stay within the max depth.
4. If the deep keys come from untrusted input, treat this error as the guard working — reject the request rather than raising the limit.

Example fix

// before
const form = new FormData();
form.append('a[b][c][d][e][f][g]', value); // exceeds max depth
axios.post('/api', form);
// after
axios.post('/api', { a: { b: { c: { d: { e: { f: { g: value } } } } } } }); // send as JSON

function maxFieldDepth(formData) {
  let max = 0;
  for (const [name] of formData.entries()) {
    const depth = (name.match(/\[/g) || []).length + 1;
    if (depth > max) max = depth;
  }
  return max;
}
if (maxFieldDepth(formData) > 5) {
  throw new Error('form field nesting exceeds axios max depth of 5');
}

try {
  const res = await axios.post(url, formData);
} catch (err) {
  if (err.code === 'ERR_FORM_DATA_DEPTH_EXCEEDED') {
    // flatten the payload or send JSON instead
  } else throw err;
}

When it happens

Trigger: Posting or receiving FormData whose keys use bracket/dot path notation nested past the max depth — e.g. a field named `a[b][c][d][e][f]…` beyond the limit — anywhere axios runs formDataToJSON: serializing FormData request data to JSON, or transforming a multipart body into an object.

Common situations: Deeply nested form builders (dynamic nested arrays of objects serialized with bracket notation), frameworks like PHP/Rails-style `field[0][children][0][meta][tags][]` structures, or untrusted client input crafting deep keys. Legitimate very-deep data structures occasionally hit the default cap.

Related errors

• FormData instance required
• target must be an object
• visitor must be a function
• ERR_NOT_SUPPORT
• ERR_FORM_DATA_DEPTH_EXCEEDED

AI-assisted analysis of axios/axios@c3f553c740 (2026-07-31). Data as JSON: /data/errors/dde2d59fa08addf2.json. Report an issue: GitHub.