Diagnosing Storybook 'Module not found' Errors During Build

Recognizable condition

When running npm run storybook (or yarn storybook) the terminal shows errors such as:

ERROR in ./src/components/Button.stories.tsx
Module not found: Error: Can't resolve '../components/Button' in '/path/to/project/.storybook'

Or Storybook starts but fails to load a story with a red box indicating "Cannot find module" for a component that exists in the repository.

Cause / Diagnostic table

Possible cause	Typical symptom
Incorrect relative path in a .stories file	Error points to a specific story file and the missing module is a relative import.
Stories pattern in .storybook/main.js does not match actual file locations	Storybook logs "No stories found" or skips entire directories.
Missing or incompatible peer dependencies (e.g., @storybook/addon-essentials)	Build succeeds but stories throw runtime errors like "Invalid hook call" or "Component is not a function".
Webpack/Vite overrides unintentionally exclude source folders	Storybook resolves modules from node_modules but cannot find your src/ code.
Stale caches in .storybook or node_modules	Errors persist after fixing paths; restarting Storybook does not clear them.

Ordered checks

1. Verify story file imports

   Open the failing .stories.tsx or .stories.jsx file and check every relative import. Ensure the path correctly reaches the component from the story file’s location.

   // Example: story file at src/components/Button.stories.tsx
   import { Button } from './Button'; // correct if Button.tsx is in same folder
   // Incorrect: import { Button } from '../Button'; // points one level up
   

2. Inspect the stories array in .storybook/main.js

   Confirm that the glob pattern includes the directory where your stories live and that it uses the correct file extension.

   // .storybook/main.js
   module.exports = {
     stories: ['../src/**/*.stories.@(tsx|jsx)'], // adjust if stories are elsewhere
     addons: ['@storybook/addon-essentials'],
   };
   

   If you moved stories to a new folder (e.g., src/features), update the pattern accordingly.

3. Check for missing peer dependencies

   Run npm ls @storybook/addon-essentials (or yarn equivalent) to see if the package is installed and matches the Storybook version.

   # Example output indicating a mismatch
   @storybook/addon-essentials@7.0.0
   ├─ UNMET PEER DEPENDENCY @storybook/api@7.0.0
   └─ @storybook/components@7.0.0
   

   If unmet peers appear, install the required versions.

4. Review Webpack/Vite overrides

   In .storybook/main.js, look for a webpackFinal or viteFinal function. Ensure it does not accidentally exclude your src directory.

   webpackFinal: (config) => {
     // Do NOT remove or alter the default resolve.modules unless you know why
     return config;
   }
   

5. Clear caches

   Delete the .storybook/cache folder (if it exists) and restart Storybook. If the problem persists, remove node_modules and the lockfile, then reinstall.

   rm -rf .storybook/cache
   rm -rf node_modules package-lock.json
   npm install
   

Fixes tied to findings

• Path mismatch – Edit the relative import in the story file to point to the correct component location.
• Stories pattern mismatch – Update the stories array in .storybook/main.js to reflect the new folder structure or file naming convention.
• Missing peer – Install the missing peer at the version Storybook expects, e.g., npm install @storybook/api@7.0.0 --save-dev.
• Overly restrictive webpack/vite rule – Remove or adjust the exclude/include rules that block src/, then restart Storybook.
• Stale cache – Clearing the cache (or a full reinstall) forces Storybook to rebuild its module graph, eliminating references to deleted or moved files.

Escalation criteria

• If after completing all checks the error still references a module that definitely exists, examine the full webpack/vite config output (npm run storybook -- --debug-webpack) for any custom aliases or fallback settings that may be overriding Node’s module resolution.
• When the problem appears only in a CI environment but not locally, compare the checked‑out branch, ensure lockfiles are identical, and run a clean install in the CI container.
• If you suspect a bug in Storybook itself (e.g., after a version upgrade), file a minimal reproducible repository and check the Storybook issue tracker for similar reports before attempting deeper configuration changes.