WSL Pitfall - Disk Format Issue with Symlinks

TL;DR

If you encounter Error: EPERM: operation not permitted, symlink or any other symlink-related errors in WSL, first check whether the disk format is NTFS or ReFS.

As usual, I was writing my annual year-in-review blog post on New Year’s Eve and ran npm install, only to be greeted with the following error:

npm ERR! code EPERM
npm ERR! syscall symlink
npm ERR! path ../esprima/bin/esparse.js
npm ERR! dest /e/hexo-blog/node_modules/.bin/esparse
npm ERR! errno -1
npm ERR! Error: EPERM: operation not permitted, symlink '../esprima/bin/esparse.js' -> '/e/hexo-blog/node_modules/.bin/esparse'
npm ERR!  [OperationalError: EPERM: operation not permitted, symlink '../esprima/bin/esparse.js' -> '/e/hexo-blog/node_modules/.bin/esparse'] {
npm ERR!   cause: [Error: EPERM: operation not permitted, symlink '../esprima/bin/esparse.js' -> '/e/hexo-blog/node_modules/.bin/esparse'] {
npm ERR!     errno: -1,
npm ERR!     code: 'EPERM',
npm ERR!     syscall: 'symlink',
npm ERR!     path: '../esprima/bin/esparse.js',
npm ERR!     dest: '/e/hexo-blog/node_modules/.bin/esparse'
npm ERR!   },
npm ERR!   stack: "Error: EPERM: operation not permitted, symlink '../esprima/bin/esparse.js' -> '/e/hexo-blog/node_modules/.bin/esparse'",
npm ERR!   errno: -1,
npm ERR!   code: 'EPERM',
npm ERR!   syscall: 'symlink',
npm ERR!   path: '../esprima/bin/esparse.js',
npm ERR!   dest: '/e/hexo-blog/node_modules/.bin/esparse',
npm ERR!   parent: 'hexo-blog'
npm ERR! }
npm ERR!
npm ERR! The operation was rejected by your operating system.
npm ERR! It is likely you do not have the permissions to access this file as the current user
npm ERR!
npm ERR! If you believe this might be a permissions issue, please double-check the
npm ERR! permissions of the file and its containing directories, or try running
npm ERR! the command again as root/Administrator.

npm ERR! A complete log of this run can be found in:
npm ERR!     /root/.npm/_logs/2021-01-01T13_14_56_876Z-debug.log

I was completely baffled. I had been using WSL for several years and had never run into this problem before. After searching around on Google, I found many articles, but the most helpful solution came from https://github.com/MicrosoftDocs/WSL/issues/26#issuecomment-206991754

The suggested fix was as follows:

Using this I’ve had some luck installing some npm modules, but it still does have issues with permission errors whenever npm tries to rename a file.

INSTALL GLOBAL NPM PACKAGES

npm config set unsafe-perm true

CLEAN CACHE

npm cache clean (Note: newer versions of npm require npm cache verify)

BYPASS SYMLINK ISSUES

npm install --no-bin-links

After running these steps, npm install did succeed.

Just when you thought you had solved the problem, reality had other plans.

I was stumped again, and in my confusion I tried a few things that turned out to be a waste of time:

• Reinstalled WSL — problem persisted.
• Reinstalled the OS — problem still persisted.

Then it suddenly hit me: this drive had previously been used as an external/portable drive. Could the file system format be wrong?

At this point, I finally spotted a glimmer of hope.

I then checked the WSL documentation (https://docs.microsoft.com/en-us/archive/blogs/wsl/wsl-file-system-support#drvfs) and found the following description — pay attention to the bolded sentence:

To facilitate interoperability with Windows, WSL uses the DrvFs file system. WSL automatically mounts all fixed drives with supported file systems under /mnt, such as /mnt/c, /mnt/d, etc. Currently, only NTFS and ReFS volumes are supported.

I then reformatted the drive as NTFS and tried again. Everything worked perfectly.