npm ERR! Cannot read properties of null (reading 'matches')

Problem

The error npm ERR! Cannot read properties of null (reading 'matches') occurs during package installation with npm, often accompanied by dependency-related warnings. Key characteristics of this issue:

• Typically appears after running npm install in a project directory
• Frequently occurs when attempting to use npm in a project previously managed by pnpm
• Often includes peer dependency warnings in the error output
• Common with Node.js v18+ and npm v9+
• Persists even after clearing npm cache or changing registry mirrors

Example error output:

npm ERR! Cannot read properties of null (reading 'matches')
npm ERR! A complete log of this run can be found in:
npm ERR!     /path/to/logs/debug.log

Solutions

Primary Fix: Remove node_modules and Reinstall

The most effective solution is to remove the existing dependency folders and reinstall using a consistent package manager:

# Remove both node_modules and lock files
rm -rf node_modules
rm -f package-lock.json
rm -f pnpm-lock.yaml

# Then reinstall using either:
npm install     # For npm projects
# OR
pnpm install    # For pnpm projects

Ensure Package Manager Consistency

IMPORTANT

Never mix npm and pnpm commands in the same project

1. Stick to one package manager per project
   Check for lock files to determine which manager your project uses:

   • package-lock.json → Use npm install
   • pnpm-lock.yaml → Use pnpm install

   # Check for lock files
   ls -la | grep -E 'package-lock|pnpm-lock'

2. Enforce package manager in package.json
   Add the packageManager field to prevent accidental use of wrong commands:

   {
     "name": "your-project",
     "packageManager": "pnpm@9.7.1"  // Specify your version
   }

   After adding this, tools like create-next-app will automatically use the specified package manager.

Alternative Solutions

1. Network issues
   If you suspect network problems (common with certain firewalls):

   # Try changing networks
   npm install --fetch-retries=5 --fetch-retry-mintimeout=20000
   
   # Or use mirrors (for China)
   npm config set registry https://registry.npmmirror.com

2. Clean reinstallation with pnpm
   If switching to pnpm:

   # Remove existing files
   rm -rf node_modules package-lock.json
   
   # Generate fresh pnpm installation
   pnpm install

3. Verify engine compatibility
   Ensure your Node.js version matches project requirements in package.json:

   "engines": {
     "node": ">=18.0.0"
   }

Prevention Tips

AVOID

Running npm install in a project that contains pnpm-lock.yaml

• Use nvm to manage Node.js versions across projects
• Configure VS Code to use project-specific package managers
• Add package manager hint to your project README:

  ## Installation
  
  This project uses pnpm:
  ```bash
  pnpm install

Conclusion

The "Cannot read properties of null" error typically stems from package manager conflict between npm and pnpm. The guaranteed solution requires:

1. Complete removal of node_modules and lock files
2. Consistent reinstallation using either npm or pnpm
3. Declaration of packageManager in package.json for enforcement

This approach resolves the core conflict that triggers the "reading 'matches'" type error during dependency resolution.