A tsconfig paths alias is not found by TypeScript or by the build
An import such as @/components/button is underlined in the editorShort answer
The paths option only tells TypeScript how to find types; it does not change emitted imports. First check the targets: they are relative to baseUrl, or to tsconfig.json when baseUrl is unset. Then give the bundler or test runner the same alias: Vite resolve.alias, webpack resolve.alias or Jest moduleNameMapper.
Fix it fast
1Find out which cause you have
Open the tsconfig.json that covers the failing file and read its paths and baseUrl entries. Every cause below starts from them.
grep -n -A6 "paths\|baseUrl" tsconfig.json2Match what you see, then jump to its fix
- 1
The alias target names a folder that does not exist from the base folderThe paths target does not point at the real folderFix - 2
tsc passes but the dev server or build cannot resolve the importThe bundler does not read paths (Vite or webpack)Fix - 3
The app runs, but tests fail to resolve the importThe test runner does not know the alias (Jest)Fix - 4
A webpack build, not a Vite one, fails on the aliaswebpack has no matching resolve.aliasFix
- 1
What does the error look like?
An import such as @/components/button is underlined in the editortsc is happy but the dev server or the test runner cannot find the same import
Cause 1 of 4
The paths target does not point at the real folder
1Check
paths targets are relative to baseUrl if it is set, otherwise to the tsconfig file. A src/ folder missing from the target is the usual slip.
ls src/components2Fix
Make the target match the folder from the right base.
{
"compilerOptions": {
"paths": {
"@/*": ["./src/*"]
}
}
}3Verify
Restart the TypeScript server and check the import no longer has a squiggle, then run the type check.
npx tsc --noEmitConfirmed by typescriptlang.org
Cause 2 of 4
The bundler does not read paths (Vite or webpack)
1Check
The TypeScript docs say paths does not change how imports are emitted, so another tool must apply the mapping at bundle time.
grep -n "alias" vite.config.* webpack.config.*2Fix
Add the same alias to the bundler config. Vite advises absolute file system paths for aliases.
// vite.config.ts
import path from 'node:path';
import { defineConfig } from 'vite';
export default defineConfig({
resolve: {
alias: { '@': path.resolve(__dirname, 'src') },
},
});3Verify
Start the dev server and open a page that uses the alias.
npm run devConfirmed by vite.dev
Cause 3 of 4
The test runner does not know the alias (Jest)
1Check
Jest has its own resolver. It maps module names with regular expressions in moduleNameMapper.
grep -rn "moduleNameMapper" jest.config.*2Fix
Add an anchored pattern that maps the alias to the folder with <rootDir>.
// jest.config.js
module.exports = {
moduleNameMapper: {
'^@/(.*)$': '<rootDir>/src/$1',
},
};3Verify
Run the tests.
npx jestConfirmed by jestjs.io
Cause 4 of 4
webpack has no matching resolve.alias
1Check
webpack uses resolve.alias and gives it precedence over other module resolution.
grep -n "alias" webpack.config.*2Fix
Add the alias with an absolute path.
resolve: {
alias: {
'@': path.resolve(__dirname, 'src'),
},
},3Verify
Run the build.
npx webpackConfirmed by webpack.js.org
How do I stop it coming back?
- Define each alias twice on purpose: once in tsconfig for types, once in the tool that runs the code.
- Use Next.js when you want one source of truth: it supports the paths and baseUrl options of tsconfig.json itself.
- Anchor Jest patterns with ^ and $.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- TaskvareA task and project-management suite: React on the web, Flutter on mobile, TypeScript underneath.
Related fixes
Web apps
TypeScript rejects the authorize function of the Credentials provider
A custom field you return from authorize is missing on the User or Session type
The authorize callback must return either a user object or null.
3 causes, each with a fixWeb apps
The user is undefined inside the NextAuth session callback
session.user.id is undefined
With JWT sessions, NextAuth gives the session callback a token, not a user.
3 causes, each with a fixWeb apps
Upgrading to Next.js 16: middleware becomes proxy, and the other things that break
Missing Required default.js for Parallel Route
Next.js 16 renames middleware.ts to proxy.ts and its exported function to proxy.
6 causes, each with a fixWeb apps
next build stops because of TypeScript errors
How to disable typescript for failing my builds with nextjs?
next build runs a TypeScript check and fails the build when it finds type errors.
2 causes, each with a fixWeb apps
TypeScript cannot resolve import './globals.css' in Next.js
ts(2882)
TypeScript now checks imports like import './globals.css' when noUncheckedSideEffectImports is on, and it finds no type for a CSS file.
2 causes, each with a fixWeb apps
getStaticProps is ignored or rejected in a Next.js project
How to fetch data server-side in the latest Next.js? Tried getStaticProps but it's not running and getting undefined
getStaticProps belongs to the Pages Router.
4 causes, each with a fix