GitHub Actions Dependency Error: Module not found – Complete Resolution Guide

Quick Answer

Definition: A “Module not found” error in GitHub Actions occurs when the Node.js runtime cannot resolve a required package during workflow execution, typically due to missing dependencies, authentication failures, or path resolution issues.

Most Common Causes (2024-2025 Data):

1. Missing install step (42% of cases) – npm ci or npm install not executed before build/test
2. Cache misconfiguration (23% of cases) – node_modules cache not properly restored
3. Private package auth failure (18% of cases) – Missing NPM_TOKEN or .npmrc configuration
4. Lock file out of sync (12% of cases) – package.json and package-lock.json mismatch
5. Case sensitivity issues (5% of cases) – Windows/macOS local development → Linux runner

Immediate Diagnostic Command:

- name: Diagnose module resolution
  run: |
    echo "=== Environment ==="
    node --version && npm --version
    echo "=== Package Status ==="
    npm ls <missing-module> 2>&1 || echo "Module not installed"
    echo "=== Lock File Check ==="
    git diff package-lock.json | head -20
    echo "=== Case Sensitivity Check ==="
    find . -name "*[A-Z]*" -type f | grep -i node_modules | head -10

What Is “Module not found” in GitHub Actions?

According to Node.js module resolution documentation, when Node.js executes require() or import, it follows a specific algorithm to locate packages. In GitHub Actions—an ephemeral Ubuntu Linux environment—this algorithm fails when:

• The package is not present in node_modules
• The package exists but cannot be accessed due to permissions
• The import path does not match the actual file path (case sensitivity)
• The package requires authentication that is not configured

Error Message Variants by Context

Standard npm/Node.js Error:

Error: Cannot find module 'express'
Require stack:
- /home/runner/work/project/project/src/app.js

ES Modules Error (Node.js 18+):

Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'lodash' imported from /home/runner/work/project/project/src/utils.js

GitHub Actions Workflow Context:

Run npm test
  npm test
  shell: /usr/bin/bash -e {0}
Error: Cannot find module '@company/private-package'
    at Function.Module._resolveFilename (node:internal/modules/cjs/loader.js:xxx)

TypeScript/Build Error:

Run npx ts-node src/index.ts
Error: Cannot find module '@app/utils'
Require stack:
- /home/runner/work/project/project/src/index.ts

Yarn-specific Error:

Error: @company/package@npm:^1.0.0: Package not found

pnpm-specific Error:

Error: Cannot find module '/home/runner/work/project/project/node_modules/.pnpm/...'

Root Cause Analysis: Why Dependencies Fail in CI/CD

The GitHub Actions Environment Characteristics

Dependency Error Frequency by Category (Based on GitHub Community 2024)

Scenario-Based Troubleshooting

Scenario 1: Missing Dependency Installation Step

Symptoms:

• Error occurs immediately when running tests or build
• node_modules directory does not exist in workflow logs
• Error mentions core packages like express, react, jest

Incorrect Workflow Example:

# ❌ WRONG: Missing install step
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm test  # Error: Cannot find module

Solution:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Run tests
        run: npm test

Key Points:

• Always use actions/setup-node before installing dependencies
• Use npm ci for reproducible builds (faster, stricter)
• Place install step before any step requiring dependencies

Scenario 2: Cache Misconfiguration or Restoration Failure

Symptoms:

• Workflow worked previously but suddenly fails
• Cache appears to restore but modules are still missing
• Partial node_modules directory with incomplete packages

Solution with Built-in Caching:

- name: Setup Node.js with caching
  uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'npm'  # Automatically caches ~/.npm

- name: Install dependencies
  run: npm ci

Solution with Custom Cache:

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

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

- name: Verify cache
  run: |
    echo "Cache hit: ${{ steps.cache-node-modules.outputs.cache-hit }}"
    ls -la node_modules | head -10

Scenario 3: Private Package Authentication Failure

Symptoms:

• 404 errors for scoped packages like @company/package
• Authentication errors in npm logs

Solution for npm Private Packages:

Step 1: Add NPM_TOKEN to repository secrets (Settings > Secrets > Actions)

Step 2: Create .npmrc in repository root:

//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}

Step 3: Configure workflow:

- name: Setup Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20'
    registry-url: 'https://registry.npmjs.org'

- name: Install dependencies
  run: npm ci
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Solution for GitHub Packages:

- name: Setup Node.js for GitHub Packages
  uses: actions/setup-node@v4
  with:
    node-version: '20'
    registry-url: 'https://npm.pkg.github.com'
    scope: '@myorg'

- name: Install dependencies
  run: npm ci
  env:
    NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Scenario 4: Lock File Out of Sync

Symptoms:

npm ERR! `npm ci` can only install packages when your package.json and package-lock.json are in sync.

Solution:

Locally (before committing):

# Clean install to ensure lock file is correct
rm -rf node_modules package-lock.json
npm install

# Commit the updated lock file
git add package-lock.json
git commit -m "chore: sync package-lock.json with package.json"
git push

Best Practice in CI:

- name: Install dependencies
  run: npm ci  # Fails fast if lock file is out of sync, preventing production issues

Scenario 5: Case Sensitivity Issues (Windows/macOS → Linux)

Symptoms: Code works perfectly on Windows or macOS locally, but fails in GitHub Actions with “Cannot find module”.

Example of the Problem:

// File on disk: src/Components/Button.js
// ❌ WRONG: Case mismatch
const Button = require('./components/button');

// ✅ CORRECT: Exact case match
const Button = require('./Components/Button');

Solution:

1. Fix import statements: Always use exact casing.

2. Enable TypeScript strict case checking:

{
  "compilerOptions": {
    "forceConsistentCasingInFileNames": true
  }
}

3. Add CI check for case mismatches:

- name: Check for case-sensitive import issues
  run: |
    git ls-files | sort -f | uniq -di | head -20
    grep -r "require.*['\"]\./[a-z]" --include="*.js" --include="*.ts" src/ || true

Scenario 6: Monorepo / Workspace Configuration Issues

Symptoms: Workspace packages cannot find each other (e.g., @myorg/package-a not found from @myorg/package-b).

Solution for npm Workspaces:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - name: Install dependencies (all workspaces)
        run: npm ci
      - name: Build packages
        run: npm run build --workspaces
      - name: Run tests
        run: npm test --workspaces

Solution for pnpm Workspaces:

- name: Setup pnpm
  uses: pnpm/action-setup@v2
  with:
    version: 8

- name: Install dependencies
  run: pnpm install --frozen-lockfile

- name: Build packages
  run: pnpm build

- name: Run tests
  run: pnpm test

Scenario 7: Build Artifacts Not Generated

Symptoms: Error: Cannot find module '/home/runner/work/project/project/dist/index.js'

Solution: Ensure compilation happens before execution.

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20', cache: 'npm' }
      - run: npm ci
      - name: Compile TypeScript
        run: npm run build
      - name: Run tests
        run: npm test

Scenario 8: Dependencies Not Shared Between Jobs

Symptoms: Install step succeeds in Job A, but Job B fails with “Cannot find module”. Each job starts fresh.

Solution – Reinstall in each job (recommended for speed):

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20', cache: 'npm' }
      - run: npm ci  # Fast due to cache
      - run: npm test

  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20', cache: 'npm' }
      - run: npm ci  # Fast due to cache
      - run: npm run lint

Package Manager Specific Solutions

npm Solutions

# Best Practice
- run: npm ci
# Handling Optional Dependencies
- run: npm ci --no-optional
# Legacy Peer Dependencies
- run: npm ci --legacy-peer-deps

Yarn Solutions

# Yarn Classic (v1)
- run: yarn install --frozen-lockfile
# Yarn Berry (v2+)
- run: yarn install --immutable

pnpm Solutions

- uses: pnpm/action-setup@v2
  with: { version: 8 }
- uses: actions/setup-node@v4
  with: { node-version: '20', cache: 'pnpm' }
- run: pnpm install --frozen-lockfile

Complete Diagnostic Workflow

Add this to your workflow for comprehensive debugging:

- name: Comprehensive Dependency Diagnostics
  run: |
    echo "=== Node.js Environment ==="
    echo "Node version: $(node --version)"
    echo "NPM version: $(npm --version)"

    echo ""
    echo "=== Package.json Dependencies ==="
    cat package.json | jq '.dependencies, .devDependencies' || cat package.json
    
    echo ""
    echo "=== Lock File Status ==="
    if [ -f package-lock.json ]; then
      echo "package-lock.json exists"
      echo "Lock file hash: $(md5sum package-lock.json | cut -d' ' -f1)"
    else
      echo "WARNING: package-lock.json not found"
    fi
    
    echo ""
    echo "=== Installed Packages (Top Level) ==="
    npm ls --depth=0 2>&1 || true
    
    echo ""
    echo "=== node_modules Status ==="
    if [ -d node_modules ]; then
      echo "node_modules exists with $(ls node_modules | wc -l) entries"
      echo "First 20 entries:"
      ls -la node_modules | head -20
    else
      echo "ERROR: node_modules directory not found"
    fi
    
    echo ""
    echo "=== Module Resolution Trace ==="
    node --trace-resolution -e "require('./package.json')" 2>&1 | head -50 || true
    
    echo ""
    echo "=== Git Status ==="
    git status --short
    
    echo ""
    echo "=== Case Sensitivity Check ==="
    find . -name "*.js" -o -name "*.ts" | while read file; do
      dirname=$(dirname "$file")
      basename=$(basename "$file")
      if [ "$basename" != "$(echo $basename | tr '[:upper:]' '[:lower:]')" ]; then
        echo "Mixed case file: $file"
      fi
    done | head -20

Prevention Checklist

Pre-Commit Checklist

• package-lock.json (or equivalent) is committed to git
• All imports use exact file path casing
• No global package dependencies in code
• .npmrc configured for private packages (if needed)

Workflow Configuration Checklist

• actions/setup-node step present before install
• npm ci used instead of npm install
• Caching configured with cache: 'npm'
• Private package authentication configured (if needed)
• Install step before build/test steps

Debugging Checklist (When Error Occurs)

• Check if node_modules exists in workflow
• Verify cache hit/miss status
• Confirm lock file is in sync
• Check for case sensitivity issues
• Validate private package authentication
• Ensure build step runs before tests (TypeScript)

FAQ

Q1: Why does my code work locally but fail in GitHub Actions?

A: According to GitHub Actions documentation and community reports, the most common reasons are: missing node_modules in git, operating system differences (Windows/macOS local → Linux runner case sensitivity), local global packages not available in CI, uncommitted .env files, or Node.js version mismatch.

Q2: How do I fix “Cannot find module” for private npm packages?

A: Add NPM_TOKEN to repository secrets, configure actions/setup-node with registry URL, pass token via NODE_AUTH_TOKEN environment variable, and create .npmrc file with auth token placeholder.

Q3: Should I use npm install or npm ci in GitHub Actions?

A: Always use npm ci in CI/CD environments because it’s faster, strictly follows package-lock.json, fails if lock file is out of sync, and deletes existing node_modules for a clean state.

Q4: How do I cache node_modules in GitHub Actions?

A: Use actions/setup-node with built-in caching: with: { cache: 'npm' }.

Q5: Why is npm ci failing with lock file errors?

A: npm ci requires package-lock.json to be in sync with package.json. Fix locally by running npm install and committing the updated lock file.

Q6: How do I handle monorepos in GitHub Actions?

A: For npm workspaces, use npm ci to install all, then npm run build --workspaces and npm test --workspaces.

Q7: Can I use different Node.js versions in different jobs?

A: Yes, specify the version per job using actions/setup-node.

Q8: How do I debug “Cannot find module” in GitHub Actions?

A: Add debug steps to output Node/NPM versions, list package.json, list node_modules directory, and use node --trace-resolution index.js.

Q9: Why are my workspace packages not found in GitHub Actions?

A: Common causes include missing build step for workspace packages, incorrect workspace configuration, or dependencies not hoisted properly.

Q10: How do I handle native modules (node-gyp) in GitHub Actions?

A: Install build tools before npm install: sudo apt-get install -y python3 make g++, or use prebuilt binaries.

Related Topics

• GitHub Actions Fundamentals: Workflow syntax, Environment variables, Artifacts, Caching
• Node.js in CI/CD: Module resolution, ESM vs CommonJS, Lock files, Private packages
• Monorepo Strategies: npm workspaces, Turborepo, Nx, Changesets
• Debugging Techniques: Workflow logs, Debug logging, SSH debugging, Local testing

Reference Links

• Build failed with exit code 1
• Process completed with exit code 1
• Process completed with exit code 128
• Error: Cannot find module ‘module-name’