---
name: resolve-pnpm-catalog-dependency-errors
category: devops
description: Resolve pnpm catalog dependency errors for @types/node in monorepo with Node 20 by bypassing catalog, ensuring compatible pnpm version, and installing TypeScript and @types/node as workspace devDependencies.
---

## When to use
You are working with a pnpm monorepo that uses the `catalog` field to manage dependency versions. You encounter errors like:
```
ERR_PNPM_SPEC_NOT_SUPPORTED_BY_ANY_RESOLVER: @types/node@catalog: isn't supported by any available resolver
```
or similar catalog resolution issues, especially when using Node.js versions <22 (e.g., Node 20) and trying to install TypeScript or @types/node.

## Steps
1. **Ensure a compatible pnpm version**  
   Node 20.x works well with pnpm 6 or 8. Avoid pnpm ≥11 which requires Node ≥22.  
   ```bash
   npm remove -g pnpm
   npm install -g pnpm@8   # or pnpm@6 if you prefer
   pnpm -v   # should show 8.x
   ```

2. **Configure pnpm to bypass the catalog for problematic packages**  
   Create (or edit) a `.npmrc` file in the repository root:
   ```bash
   echo "registry=https://registry.npmjs.org/" > .npmrc
   echo "catalog=false" >> .npmrc
   ```
   This tells pnpm to fetch packages from the regular npm registry instead of trying to resolve them through the catalog.

3. **Clean any existing lockfile**  
   ```bash
   rm -f pnpm-lock.yaml
   ```

4. **Install dependencies, ignoring engine checks if needed**  
   Node 20 is older than the engine requirement for some pnpm versions; bypass the check:
   ```bash
   export PNPM_IGNORE_ENGINE_CHECK=1
   pnpm install --ignore-scripts
   ```

5. **Add TypeScript and Node typings as workspace devDependencies**  
   Installing them as regular devDependencies (not relying on catalog) ensures they are resolvable:
   ```bash
   pnpm add -D -w typescript @types/node
   ```

6. **Run the build**  
   ```bash
   pnpm run build
   ```
   After this step you should see a successful build and fresh static assets (e.g., `index.html`, `assets/`) in the repository root.

7. **Deploy the built files** (if applicable)  
   ```bash
   mkdir -p /var/www/sailor.bar
   rsync -av --exclude='.git' . /var/www/sailor.bar/
   nginx -t && systemctl reload nginx
   ```

## Verification
- Check that `tsc` is available: `pnpm exec tsc --version` should print a version.
- Confirm the site serves the updated content:
  ```bash
  curl -s http://localhost/ | grep -i sailor
  # Should output something like <title>Sailor.bar</title>
  ```

## Notes
- The `.npmrc` changes are local to the repository; they do not affect global pnpm behavior.
- If you later upgrade Node to ≥22, you can revert to using the catalog by removing the `.npmrc` lines or setting `catalog=true`.
- This approach also resolves similar catalog resolution errors for other packages (e.g., `@replit/vite-plugin-cartographer`) that may appear in the same monorepo.

## References
- pnpm catalog documentation: https://pnpm.io/package_json#catalog
- Node.js version compatibility with pnpm: https://pnpm.io/installation#version-compatibility