Fix ModuleNotFoundError: Module not found: Can't resolve '@/components/Header' in Next.js

This error occurs when Next.js cannot resolve a module path, usually because the path alias is misconfigured in tsconfig.json or the file does not exist at the expected location. Fix it by verifying the paths mapping in tsconfig.json matches your directory structure and the target file exists.

Reading the Stack Trace

Here's what each line means:

• at /app/node_modules/webpack/lib/Compilation.js:2016:28: Webpack's compilation step failed because the module could not be resolved in the dependency graph.
• at /app/node_modules/enhanced-resolve/lib/AliasPlugin.js:46:12: The alias resolution plugin tried the configured path aliases but found no matching file.
• at /app/node_modules/enhanced-resolve/lib/Resolver.js:312:5: The resolver exhausted all configured paths and extensions without finding a valid module.

Common Causes

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2017",
    "module": "esnext"
    // No paths or baseUrl configured
  }
}

// src/pages/index.tsx
import Header from '@/components/Header'; // File was renamed to NavHeader.tsx

// The file is Header.jsx but tsconfig resolves only .ts and .tsx
import Header from '@/components/Header';

The Fix

Add baseUrl and paths to tsconfig.json so that the @ alias resolves to the src directory. This allows webpack and TypeScript to find modules imported with the @/ prefix.

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2017",
    "module": "esnext",
    "jsx": "preserve"
  },
  "include": ["src"]
}

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2017",
    "module": "esnext",
    "jsx": "preserve",
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  },
  "include": ["src"]
}

Testing the Fix

import { render, screen } from '@testing-library/react';
import Header from '@/components/Header';

describe('Header', () => {
  it('resolves the @/ alias and renders the header', () => {
    render(<Header />);
    expect(screen.getByRole('banner')).toBeInTheDocument();
  });

  it('renders navigation links', () => {
    render(<Header />);
    expect(screen.getByRole('navigation')).toBeInTheDocument();
  });
});

Run your tests:

npm test

Pushing Through CI/CD

git checkout -b fix/module-not-found-path-alias,git add tsconfig.json,git commit -m "fix: add baseUrl and paths alias to tsconfig.json",git push origin fix/module-not-found-path-alias

Your CI config should look something like this:

name: CI
on:
  pull_request:
    branches: [main]
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
      - run: npm test -- --coverage
      - run: npm run build

The Full Manual Process: 18 Steps

Here's every step you just went through to fix this one bug:

1. Notice the error alert or see it in your monitoring tool
2. Open the error dashboard and read the stack trace
3. Identify the file and line number from the stack trace
4. Open your IDE and navigate to the file
5. Read the surrounding code to understand context
6. Reproduce the error locally
7. Identify the root cause
8. Write the fix
9. Run the test suite locally
10. Fix any failing tests
11. Write new tests covering the edge case
12. Run the full test suite again
13. Create a new git branch
14. Commit and push your changes
15. Open a pull request
16. Wait for code review
17. Merge and deploy to production
18. Monitor production to confirm the error is resolved

Total time: 30-60 minutes. For one bug.

npm install bugstack-sdk

import { initBugStack } from 'bugstack-sdk'

initBugStack({ apiKey: process.env.BUGSTACK_API_KEY })

Deploying the Fix (Manual Path)

1. Verify tsconfig.json has the correct paths alias configuration.
2. Run the Next.js build locally to confirm all imports resolve.
3. Open a pull request with the tsconfig.json changes.
4. Wait for CI checks to pass on the PR.
5. Merge to main and verify the build succeeds in staging.

Frequently Asked Questions