# NPM Install Failed in CI

Common Error Patterns

npm install failures typically show:

bash
npm ERR! code E404
npm ERR! 404 Not Found - GET https://registry.npmjs.org/package
bash
npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
bash
npm ERR! code ENOENT
npm ERR! syscall spawn git
npm ERR! errno ENOENT
bash
npm ERR! network timeout
npm ERR! fetch failed
bash
npm ERR! peer dep missing: package@version, required by another-package

Root Causes and Solutions

1. Registry Authentication Failure

Cannot access private registry or packages.

Solution:

Configure npm registry:

```bash npm config set registry https://registry.npmjs.org/

# For private registry (npm Enterprise, Artifactory) npm config set registry https://your-registry.com/ ```

Authenticate with private registry:

```bash npm login --registry=https://your-registry.com/

# Or use auth token npm config set //your-registry.com/:_authToken ${NPM_TOKEN} ```

In CI:

```yaml # GitHub Actions - name: Configure npm env: NPM_TOKEN: ${{ secrets.NPM_TOKEN }} run: | npm config set //registry.npmjs.org/:_authToken ${NPM_TOKEN} npm install

# Or use .npmrc file - name: Setup .npmrc run: echo "//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}" > .npmrc

  • name: Install dependencies
  • run: npm ci
  • `

2. Dependency Resolution Conflict

Conflicting peer dependencies or version requirements.

Solution:

Use legacy peer deps resolution:

bash
npm install --legacy-peer-deps

Or force resolution:

bash
npm install --force

Better approach - resolve conflicts properly:

```bash # Check dependency tree npm ls package-name

# Audit for vulnerabilities npm audit fix

# Update lockfile npm update ```

In CI:

yaml
- name: Install dependencies
  run: npm ci --legacy-peer-deps

3. Package Not Found

Package doesn't exist or is private.

Solution:

Verify package exists:

bash
npm view package-name
npm search package-name

Check registry:

bash
npm config get registry
curl -s https://registry.npmjs.org/package-name

For scoped packages, ensure correct scope:

```bash # Check @scope/package npm view @scope/package

# Configure scope registry npm config set @scope:registry https://scope-registry.com/ ```

4. Lockfile Out of Sync

package-lock.json doesn't match package.json.

Solution:

Regenerate lockfile:

bash
rm package-lock.json
npm install

Or update lockfile:

bash
npm install --lockfile-version 2

Use npm ci for CI environments:

bash
# npm ci uses lockfile exactly, faster and safer
npm ci

In CI:

yaml
- name: Install dependencies
  run: npm ci  # Uses lockfile, faster than npm install

5. Network/Timeout Issues

Slow or unreliable network connection.

Solution:

Increase timeout:

bash
npm install --fetch-timeout=60000
npm config set fetch-timeout 60000
npm config set fetch-retry-maxtimeout 120000

Use mirror registry:

```bash # Use npm mirror npm config set registry https://registry.npmmirror.com/

# Switch back to default npm config set registry https://registry.npmjs.org/ ```

In CI:

yaml
- name: Install dependencies
  run: npm ci --fetch-timeout=60000
  timeout-minutes: 10

6. Git Dependencies Fail

Cannot clone git-based dependencies.

Solution:

Ensure git is available:

bash
git --version

For private git repos:

```yaml # GitHub Actions - name: Setup git credentials run: | git config --global url."https://${{ secrets.GITHUB_TOKEN }}@github.com".insteadOf "https://github.com"

  • name: Install dependencies
  • run: npm ci
  • `

For SSH git URLs:

bash
# Configure SSH
ssh-keyscan github.com >> ~/.ssh/known_hosts

7. Cache Corruption

npm cache causing installation issues.

Solution:

Clear npm cache:

bash
npm cache clean --force
rm -rf node_modules
npm install

In CI:

```yaml - name: Clear npm cache run: npm cache clean --force

  • name: Install dependencies
  • run: npm ci
  • `

8. Node Version Mismatch

Node version incompatible with packages.

Solution:

Check Node version:

bash
node --version
npm --version

Use correct Node version:

```yaml # GitHub Actions - name: Setup Node uses: actions/setup-node@v4 with: node-version: '18' cache: 'npm'

  • name: Install dependencies
  • run: npm ci
  • `

Check package requirements:

json
// package.json
{
  "engines": {
    "node": ">=18.0.0",
    "npm": ">=9.0.0"
  }
}

CI Caching Configuration

GitHub Actions Cache

```yaml - name: Setup Node uses: actions/setup-node@v4 with: node-version: '18' cache: 'npm'

  • name: Install dependencies
  • run: npm ci
  • `

Custom Cache Strategy

```yaml - name: Cache node modules uses: actions/cache@v4 id: cache-npm with: path: | ~/.npm node_modules key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }} restore-keys: | ${{ runner.os }}-node-

  • name: Install dependencies
  • if: steps.cache-npm.outputs.cache-hit != 'true'
  • run: npm ci
  • `

GitLab CI Cache

```yaml cache: key: files: - package-lock.json paths: - node_modules/

install: script: - npm ci ```

CircleCI Cache

```yaml steps: - restore_cache: keys: - node-v1-{{ checksum "package-lock.json" }} - node-v1-

  • run: npm ci
  • save_cache:
  • key: node-v1-{{ checksum "package-lock.json" }}
  • paths:
  • - node_modules
  • - ~/.npm
  • `

Debugging Commands

```bash # Verbose output npm install --loglevel verbose

# Debug mode npm install --loglevel silly

# Dry run npm install --dry-run

# Check what would be installed npm ls --depth=0

# Check dependency tree npm ls package-name

# Check for duplicates npm dedupe

# Check outdated packages npm outdated

# Validate package.json npm pkg fix ```

Best Practices

Use npm ci in CI

```yaml # ALWAYS use npm ci in CI, not npm install - run: npm ci # Faster, uses lockfile, fails on mismatch

# NEVER use npm install in CI - run: npm install # Updates lockfile, slower, unpredictable ```

Lockfile Version

json
// package.json
{
  "packageManager": "npm@9.0.0"
}

Prevent Uncommitted Changes

yaml
- name: Check lockfile
  run: |
    npm install --package-lock-only
    git diff --exit-code package-lock.json

Quick Reference

ErrorSolution
E404 Not FoundCheck registry and package name
ERESOLVE conflictUse --legacy-peer-deps
EACCES permissionFix npm permissions
ETIMEDOUTIncrease timeout, use mirror
ENOENT gitSetup git credentials
Lockfile mismatchUse npm ci

Prevention Tips

  1. 1.Always use npm ci in CI, not npm install
  2. 2.Commit package-lock.json to repository
  3. 3.Use caching for faster installs
  4. 4.Pin Node version in CI
  5. 5.Configure proper registry authentication
  6. 6.Check for peer dependency conflicts early
  • [GitHub Actions Workflow Failed](#)
  • [Jenkins Build Failed](#)
  • [Test Coverage Threshold Not Met](#)