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.
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
First, verify which version of Node.js you are running:
# Check Node.js version
node --version
# Or
node -vThe recursive option requires Node.js 10.12.0 or later. If your version is older than 10.12.0, you need to upgrade.
Install a newer version of Node.js that supports the recursive option (10.12.0 or later, but 12.x LTS or newer is recommended):
Using Node Version Manager (nvm) - Linux/macOS:
# 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 --versionUsing nvm on Windows (nvm-windows):
1. Download nvm-windows from https://github.com/coreybutler/nvm-windows
2. Run the installer
3. Open PowerShell or CMD and run:
nvm install 18.0.0
nvm use 18.0.0
node --versionUsing Homebrew - macOS:
brew install node
# Or upgrade
brew upgrade nodeUsing Windows Installer:
1. Visit https://nodejs.org/
2. Download the LTS version
3. Run the installer and follow prompts
4. Restart terminal and verify: node --version
If running in Docker, update your Dockerfile to use a modern Node.js image:
Before (using outdated version):
FROM node:8
# or
FROM node:9After (using supported version):
FROM node:18-alpine
# or for more features
FROM node:18-slim
# or latest stable
FROM node:20-alpineThen rebuild your Docker image:
docker build -t myapp:latest .
docker run myapp:latestAlpine images are smaller, slim images are medium-sized, and full images include additional tools.
Check and update your continuous integration configuration:
GitHub Actions:
- uses: actions/setup-node@v3
with:
node-version: '18'GitLab CI:
image: node:18-alpine
stages:
- build
build:
script:
- npm install
- npm run buildTravis CI:
language: node_js
node_js:
- "18"Vercel/Netlify:
Check deployment settings in your dashboard and update the Node.js version there.
If your project uses nvm, update the .nvmrc file to specify a compatible version:
# 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 < .nvmrcThis ensures all developers use the same Node.js version.
If upgrading is not possible, implement a helper function that creates nested directories:
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');Or use a helper library:
const mkdirp = require('mkdirp');
mkdirp('./path/to/nested/dir').then(made => {
console.log('Created', made);
});Install mkdirp:
npm install mkdirpEnsure your entire development environment uses the updated Node.js:
# 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 --versionIf using yarn or pnpm:
# For yarn
yarn --version
yarn install
# For pnpm
pnpm --version
pnpm installNode.js Version History: The recursive option was added in Node.js 10.12.0 (released September 2018). If you're targeting end-of-life Node.js versions (like Node.js 8 or 9), consider that these versions no longer receive security updates. It's recommended to use active LTS versions: Node.js 18, 20, or newer.
Semantic Versioning in Node.js: Node.js follows semantic versioning. Even-numbered releases (10, 12, 14, 16, 18, 20) become LTS (Long Term Support) and receive 3 years of active support plus 2 years of maintenance. Odd-numbered releases (11, 13, 15, 17, 19) only get 6 months of support and should not be used in production.
fs.promises Alternative: For modern async code, consider using fs.promises instead of callbacks:
const fs = require('fs').promises;
async function createDirs() {
await fs.mkdir('./path/to/nested/dir', { recursive: true });
}
createDirs().catch(console.error);This automatically handles the recursive option and is only available in Node.js 10.13.0+.
Environment Detection: If you must support older versions, detect the feature before using it:
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);
}Package.json Engines Field: Specify minimum Node.js version in package.json to prevent installation on incompatible systems:
{
"engines": {
"node": ">=10.12.0",
"npm": ">=6.0.0"
}
}Error: Listener already called (once event already fired)
EventEmitter listener already called with once()
Error: EACCES: permission denied, open '/root/file.txt'
EACCES: permission denied
Error: Invalid encoding specified (stream encoding not supported)
How to fix Invalid encoding error in Node.js readable streams
Error: EINVAL: invalid argument, open
EINVAL: invalid argument, open
TypeError: readableLength must be a positive integer (stream config)
TypeError: readableLength must be a positive integer in Node.js streams