How to fix Error: recursive option not supported in this Node.js version in Node.js

What this error means

This error indicates that your Node.js version does not support the recursive option in the fs.mkdir() or fs.mkdirSync() functions. The recursive option, which creates all missing parent directories automatically, was introduced in Node.js 10.12.0. When you use fs.mkdir(path, { recursive: true }, callback) on an older Node.js version (before 10.12.0), Node.js throws an error because it doesn't recognize the recursive option. This is a version compatibility issue that requires either upgrading your Node.js installation or using an alternative approach to create nested directories. The error typically occurs during: - Building projects that require nested directory creation - Running tools or libraries that depend on the recursive mkdir feature - Using newer code on older Node.js environments (local development vs production server mismatch) - Executing scripts written for newer Node.js versions on legacy systems

Typical symptoms

• fs.mkdir() or fs.mkdirSync() with recursive option throws an error
• Error message contains "recursive option not supported"
• Directory creation fails even though the code looks correct
• Build or setup scripts fail during directory creation steps
• Application works on one system but not another (version mismatch)
• Testing frameworks or build tools fail to initialize properly

Common causes

1. Running code on Node.js version older than 10.12.0
2. Production server has an older Node.js version than development environment
3. Docker image or container uses an outdated Node.js base image
4. System-installed Node.js is outdated and npm/npx uses that version
5. CI/CD pipeline configured to use legacy Node.js version
6. Mismatched .nvmrc or node-version file in project

How to fix "Error: recursive option not supported in this Node.js version"

# Check Node.js version
node --version

# Or
node -v

# Install nvm if not already installed
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Reload shell configuration
source ~/.bashrc

# List available Node.js versions
nvm list-remote

# Install the latest LTS version
nvm install --lts

# Or install a specific version
nvm install 18.0.0

# Set default version
nvm alias default 18.0.0

# Switch to the new version
nvm use 18.0.0

# Verify installation
node --version

nvm install 18.0.0
nvm use 18.0.0
node --version

brew install node
# Or upgrade
brew upgrade node

FROM node:8
# or
FROM node:9

FROM node:18-alpine
# or for more features
FROM node:18-slim
# or latest stable
FROM node:20-alpine

docker build -t myapp:latest .
docker run myapp:latest

- uses: actions/setup-node@v3
  with:
    node-version: '18'

image: node:18-alpine

stages:
  - build

build:
  script:
    - npm install
    - npm run build

language: node_js
node_js:
  - "18"

# Create or update .nvmrc in your project root
echo "18.0.0" > .nvmrc

# Then developers can use
nvm use
# Or with nvm on first time
nvm install < .nvmrc
nvm use < .nvmrc

const fs = require('fs');
const path = require('path');

// Polyfill for older Node.js versions
function mkdirRecursive(dirPath) {
  if (fs.existsSync(dirPath)) {
    return;
  }

  const parentPath = path.dirname(dirPath);
  if (!fs.existsSync(parentPath)) {
    mkdirRecursive(parentPath);
  }

  fs.mkdirSync(dirPath);
}

// Usage
mkdirRecursive('./path/to/nested/dir');

const mkdirp = require('mkdirp');

mkdirp('./path/to/nested/dir').then(made => {
  console.log('Created', made);
});

npm install mkdirp

# Reinstall global tools
npm install -g npm@latest

# Verify npm version
npm --version

# Clear npm cache
npm cache clean --force

# Reinstall project dependencies
rm -rf node_modules package-lock.json
npm install

# Verify everything works
node --version
npm --version

# For yarn
yarn --version
yarn install

# For pnpm
pnpm --version
pnpm install

Advanced notes

const fs = require('fs').promises;

async function createDirs() {
  await fs.mkdir('./path/to/nested/dir', { recursive: true });
}

createDirs().catch(console.error);

const semver = require('semver');
const nodeVersion = process.version;

if (semver.gte(nodeVersion, '10.12.0')) {
  fs.mkdirSync(path, { recursive: true });
} else {
  // Use legacy approach
  mkdirRecursive(path);
}

{
  "engines": {
    "node": ">=10.12.0",
    "npm": ">=6.0.0"
  }
}

Frequently asked questions

What does "Error: recursive option not supported in this Node.js version" mean?

mkdirSync() functions. 0. js throws an error because it doesn't recognize the recursive option.

How do I fix "Error: recursive option not supported in this Node.js version"?

This error occurs when using the recursive option with fs.mkdir() or fs.mkdirSync() in an older version of Node.js that does not support this feature. The recursive option was added in Node.js 10.12.0 to create directories recursively with a single command.

What causes "Error: recursive option not supported in this Node.js version"?

Running code on Node.js version older than 10.12.0 Production server has an older Node.js version than development environment Docker image or container uses an outdated Node.js base image

Is the "Error: recursive option not supported in this Node.js version" error serious?

It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Related errors

• Error: EPERM: operation not permitted, symlink 'target' -> 'link'

  EPERM: operation not permitted, symlink on Windows (admin required)

  HIGH

• Error: EEXIST: file already exists, mkdir (directory cannot overwrite file)

  EEXIST: file already exists, mkdir (directory cannot overwrite file)

  MEDIUM

• Error: ENOSPC: no space left on device (fs.watch ran out of capacity)

  ENOSPC: No space left on device (fs.watch ran out of capacity)

  HIGH

• Error: EEXIST: file already exists, copyfile (COPYFILE_EXCL flag set)

  EEXIST: file already exists when using fs.copyFile with COPYFILE_EXCL flag

  MEDIUM

• Error: zlib error Z_DATA_ERROR (corrupted compressed data)

  Z_DATA_ERROR: Corrupted compressed data

  MEDIUM

• Error: Could not find package.json in current directory (npm module resolution)

  How to fix "Could not find package.json in current directory" in Node.js

  MEDIUM

Official resources & further reading

• 📚Node.js Official Documentation
• 📖
  Node.js API Documentation - fs.mkdir()(Official Docs)
• 📖
  Node.js Release Notes - v10.12.0(Official Docs)
• 🐙
  GitHub Issue - fs: add recursive option to mkdir/mkdirSync(GitHub)
• 📝
  npm Package - mkdirp polyfill