Fixing the 'EPERM: operation not permitted, watch' Error on macOS

Why This Error Happens

You run npm start, ready to dive into code, but your terminal hits you with a wall of red text: EPERM: operation not permitted, watch. This usually happens because macOS's security layer is blocking Node.js from monitoring your project files. It is especially common in React, Vue, or Angular projects that use fsevents to track changes.

Whether you just migrated to a new M3 Mac or updated to macOS Sonoma, the root cause is typically a permission bottleneck or a broken binary link. Here is how to clear the hurdle and get back to coding.

Step 1: Grant Full Disk Access

Apple's privacy settings have become increasingly strict. If your Terminal or VS Code isn't explicitly allowed to watch files in your folders, the system will kill the process to protect your data.

• Open System Settings.
• Go to Privacy & Security > Full Disk Access.
• Click the + icon.
• Add your terminal (Terminal, iTerm2, or Warp) and your editor (VS Code).
• Toggle the switch to ON for each.
• Crucial: Completely quit (Cmd+Q) and restart your terminal for this to take effect.

Step 2: Install Watchman

Node's default file watcher can be flaky on macOS. Meta developed a tool called watchman specifically to handle massive file trees more efficiently. It often resolves the EPERM error by providing a more robust interface for file system events.

If you have Homebrew, install it with one command:

brew install watchman

Many frameworks, including React Native, now consider Watchman a standard requirement for macOS development.

Step 3: Rebuild fsevents for Your Architecture

Did you migrate from an Intel Mac to Apple Silicon (M1/M2/M3)? If so, your node_modules might contain Intel-based binaries that can't run properly on your new chip. This mismatch frequently triggers fsevents failures.

Wipe the slate clean with these commands:

# Delete the clutter
rm -rf node_modules package-lock.json yarn.lock

# Clear the npm cache to avoid stale binaries
npm cache clean --force

# Reinstall from scratch
npm install

This forces npm to download and compile the version of fsevents that matches your current hardware.

Step 4: Fix Folder Ownership

If you ever accidentally ran sudo npm install, some files in your project now belong to the 'root' user. Your standard account doesn't have the authority to 'watch' those files, leading to an immediate EPERM crash.

Run this command to reclaim ownership of your project:

sudo chown -R $(whoami) .

This recursively changes every file in your current directory to belong to you. No more permission conflicts.

Verification: Testing the Fix

Restart your dev server by running npm start. Once it is up, open any component and add a simple console.log('test'). If your terminal shows Compiling... or Reloading... without crashing, you have successfully fixed the issue.

Pro Tips for a Smoother Workflow

• Stop using sudo: There is almost never a reason to use sudo with npm. If you find yourself needing it, your Node installation is likely configured incorrectly.
• Switch to NVM: Use Node Version Manager to install Node. It keeps everything in your user folder (/Users/name/.nvm) instead of system-protected directories.
• Manage File Limits: If your project has over 10,000 files, the OS might hit its 'open files' limit. Ensure your .gitignore includes heavy folders like dist and build to keep the watcher's workload light.