This error occurs when TypeScript cannot resolve a relative module import path, usually due to incorrect file paths, missing file extensions, case sensitivity issues, or misconfigured tsconfig.json. The fix involves verifying the import path, checking the actual file location, and configuring module resolution settings correctly.
This error means TypeScript's module resolution system cannot find the module you're trying to import with a relative path like `import { something } from './path/to/module'`. TypeScript resolves relative imports from the location of the current file, looking for a matching file with the specified path. When the file doesn't exist at that path, TypeScript raises this error. The error can occur during: - Development (in your editor with TypeScript Language Server) - Type checking (`tsc --noEmit`) - Compilation (`tsc`) - Build processes (webpack, Next.js, Vite, etc.) Common reasons include: 1. The actual file path doesn't match the import statement 2. File extension is missing or incorrect (.ts, .tsx, .js, etc.) 3. Typo in the file or folder name 4. Case sensitivity mismatch (on case-sensitive filesystems) 5. moduleResolution setting not configured correctly 6. The file exists but is outside the compiled directory structure
First, confirm the file you're importing actually exists at the specified path:
1. Look at the import statement:
import { MyComponent } from './components/MyComponent';2. From the current file, navigate to the relative path:
- If you're in src/pages/home.ts
- The import looks for: src/pages/components/MyComponent
3. Verify the file exists:
- Check if src/pages/components/MyComponent.ts exists
- Or src/pages/components/MyComponent.tsx
Use your terminal to check:
# From project root, list the target directory
ls -la src/pages/components/
# Check the exact filename
ls -la src/pages/components/MyComponent*If the file doesn't exist, the import path is wrong.
TypeScript imports often need file extensions. Check your import statement:
Without extension (may fail):
import { MyComponent } from './components/MyComponent';With extension (more reliable):
import { MyComponent } from './components/MyComponent.ts';
// or for React:
import { MyComponent } from './components/MyComponent.tsx';TypeScript resolution order (when extension is omitted):
1. MyComponent.ts
2. MyComponent.tsx
3. MyComponent.d.ts
4. MyComponent/index.ts
5. MyComponent/index.tsx
6. MyComponent/index.d.ts
Solution: Either add the extension explicitly, or rely on TypeScript's resolution order.
For Node modules and npm packages (non-relative imports), omit the extension:
import React from 'react'; // Correct
import React from 'react.ts'; // WrongOn Windows and macOS, filenames are case-insensitive. On Linux and CI/CD servers, they're case-sensitive.
This often causes issues:
- You import: ./mycomponent
- Actual file: MyComponent.ts
- Works on Windows, fails on Linux
Fix: Match the exact case:
// Wrong (will fail on Linux):
import { MyComponent } from './mycomponent';
// Correct:
import { MyComponent } from './MyComponent';Enable strict case checking in tsconfig.json:
{
"compilerOptions": {
"forceConsistentCasingInFileNames": true
}
}This makes your IDE warn you about case mismatches, catching the issue before you push to production.
Check actual filenames:
# List files with exact case
ls -la src/components/ | grep -i mycomponent
# Find the file
find src -name "*mycomponent*" -o -name "*MyComponent*"Relative paths use ./ and ../ to navigate. Make sure your path has the right depth:
Example file structure:
src/
├── pages/
│ └── home.ts
├── components/
│ └── Header.ts
└── utils/
└── helpers.tsFrom home.ts, import Header:
// Wrong (looking in wrong directory):
import { Header } from './Header'; // Looks in src/pages/, not src/components/
// Correct (go up one level, then into components):
import { Header } from '../components/Header';From home.ts, import helpers:
// Correct:
import { someHelper } from '../utils/helpers';Rules:
- ./file = same directory
- ../file = parent directory
- ../../file = grandparent directory
- ./subdir/file = subdirectory of current directory
Debug your path:
# Current file: src/pages/home.ts
# Target file: src/components/Header.ts
# From src/pages/, count steps to src/components/:
# 1. Go up: ../ (now in src/)
# 2. Go into: components/ (now in src/components/)
# Result: ../components/HeaderTypeScript needs the correct module resolution strategy. Check your tsconfig.json:
For Node.js projects (most common):
{
"compilerOptions": {
"moduleResolution": "node",
"module": "commonjs",
"target": "es2020"
}
}For ES modules or modern projects:
{
"compilerOptions": {
"moduleResolution": "node",
"module": "esnext",
"target": "es2020"
}
}If moduleResolution is "classic" (very old), change it to "node":
// Wrong (old):
{
"compilerOptions": {
"moduleResolution": "classic"
}
}
// Correct:
{
"compilerOptions": {
"moduleResolution": "node"
}
}For bundlers like Vite or webpack:
{
"compilerOptions": {
"moduleResolution": "bundler",
"module": "esnext",
"target": "es2020"
}
}Verify your setting:
# Check current tsconfig.json
cat tsconfig.json | grep -A 5 compilerOptionsFor complex folder structures, path aliases are cleaner than relative imports.
Configure in tsconfig.json:
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@components/*": ["src/components/*"],
"@utils/*": ["src/utils/*"],
"@pages/*": ["src/pages/*"],
"@/*": ["src/*"]
},
"moduleResolution": "node"
}
}Then use in your code:
// Instead of:
import { Header } from '../../../components/Header';
import { helpers } from '../../utils/helpers';
// Use cleaner aliases:
import { Header } from '@components/Header';
import { helpers } from '@utils/helpers';Benefits:
- Easier to read and refactor
- Path changes don't break imports when moving files
- IDE autocomplete works better
- Less error-prone than counting ../
Make sure bundler supports it:
- Next.js: Automatically resolves paths from tsconfig.json
- Vite: Works out of the box
- Webpack: May need tsconfig-paths-webpack-plugin
- Node.js: Needs tsconfig-paths or module-alias package
Sometimes your IDE's TypeScript server gets out of sync with your files. Restart it:
In VS Code:
1. Press Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (Mac)
2. Type: "TypeScript: Restart TS Server"
3. Press Enter
Or reload the window:
1. Ctrl+Shift+P → "Developer: Reload Window"
In WebStorm/IntelliJ:
1. Go to File > Invalidate Caches
2. Choose Invalidate and Restart
Check TypeScript version:
# Verify TypeScript is installed
npx tsc --version
# Update TypeScript if needed
npm install --save-dev typescript@latest
# Or globally
npm install -g typescript@latestClear node_modules and reinstall:
# Clear cache
npm cache clean --force
# Reinstall everything
rm -rf node_modules package-lock.json
npm installIf the file exists and the path is correct, the file might not be exporting what you're trying to import.
Check the target file exists and exports:
// MyComponent.ts - CORRECT (default export)
export default function MyComponent() {
return <div>Hello</div>;
}
// Usage:
import MyComponent from './MyComponent';// MyComponent.ts - CORRECT (named export)
export function MyComponent() {
return <div>Hello</div>;
}
// Usage:
import { MyComponent } from './MyComponent';// MyComponent.ts - WRONG (no export)
function MyComponent() {
return <div>Hello</div>;
}
// This will fail:
import { MyComponent } from './MyComponent'; // Error: not exported!Fix: Add export if missing:
// Add one of these to MyComponent.ts
// Option 1: Named export
export function MyComponent() { ... }
// Option 2: Default export
export default function MyComponent() { ... }
// Option 3: Export after definition
function MyComponent() { ... }
export { MyComponent };### Type Declaration Files (.d.ts)
If you're importing from a .d.ts file, TypeScript has specific rules:
// utils.d.ts
declare function helper(): void;
export { helper };
// Correct import:
import { helper } from './utils'; // OR './utils.d.ts'### Module Formats Mismatch
If you're mixing module formats, you may see this error:
// tsconfig.json
{
"module": "commonjs", // Compile to CommonJS
"target": "es2020"
}
// source.ts (ESM syntax)
import { something } from './other'; // Error if other.ts isn't foundSolution: Use the same module syntax throughout your project.
### Barrel Exports (index.ts)
A common pattern is to re-export from an index file:
// src/components/index.ts (barrel export)
export { Header } from './Header';
export { Footer } from './Footer';
export { Button } from './Button';
// Usage:
import { Header, Footer } from './components'; // Imports from index.tsTypeScript automatically looks for index.ts when importing a directory.
### Monorepo and Workspace Imports
In monorepo projects, configure paths for workspace packages:
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@my-org/shared/*": ["packages/shared/src/*"],
"@my-org/utils/*": ["packages/utils/src/*"]
}
}
}### Debugging with --traceResolution
Use TypeScript's built-in debugging:
# See exactly how TypeScript resolves modules
npx tsc --traceResolution --noEmit 2>&1 | head -50This shows the exact resolution path and why it fails.
### Node16/NodeNext Module Resolution
For modern Node.js versions, use newer resolution:
{
"compilerOptions": {
"moduleResolution": "node16",
"module": "es2020"
}
}This strictly enforces ES module rules and may reveal real issues with your imports.
### Source Maps and Debugging
If the error appears only at runtime but not in TypeScript:
{
"compilerOptions": {
"sourceMap": true, // Generate source maps for debugging
"strict": true // Enable strict type checking
}
}Run with source maps to trace the real import path:
node --enable-source-maps dist/index.jsFunction expression requires a return type
Function expression requires a return type
Value of type 'string | undefined' is not iterable
How to fix "Value is not iterable" in TypeScript
Type 'undefined' is not assignable to type 'string'
How to fix "Type undefined is not assignable to type string" in TypeScript
Type narrowing from typeof check produces 'never'
How to fix "Type narrowing produces never" in TypeScript
Type parameter 'T' has conflicting constraints
How to fix "Type parameter has conflicting constraints" in TypeScript