The @/ import path does not resolve in Vite, Vitest or the editor
Failed to resolve import "@/components/Header.vue" from "src/App.vue". Does the file exist?Short answer
Vite does not know what @ means until you define it in resolve.alias, with an absolute path. A tsconfig paths entry only helps the type checker. Vitest reads the alias from your Vite config, but a separate vitest.config file replaces that config unless you merge them.
Fix it fast
1Find out which cause you have
Find out where the alias is (or is not) defined: the Vite config, a separate Vitest config, and tsconfig.
ls vite.config.* vitest.config.* tsconfig*.json grep -n "alias" vite.config.* vitest.config.* 2>/dev/null2Match what you see, then jump to its fix
- 1
Failed to resolve import "@/..." in the dev server or the buildNo alias is defined in the Vite configFix - 2
The alias exists but the import still fails, often with a path like ./src in the messageThe alias path is relative, so Vite uses it as writtenFix - 3
The app builds, but only the tests fail with Failed to resolve import "@/..."A separate vitest.config file replaced the Vite configFix - 4
The editor accepts @/ imports, the bundler does nottsconfig paths is set, but Vite is not told to use itFix
- 1
What does the error look like?
Failed to resolve import "@/components/Header.vue" from "src/App.vue". Does the file exist?Failed to resolve import "@/utils" from "src/utils.test.ts". Does the file exist?
Cause 1 of 4
No alias is defined in the Vite config
1Check
Open vite.config and look for resolve.alias. A tsconfig paths entry alone does not count, because Vite does not read it by default.
grep -n -A4 "resolve" vite.config.*2Fix
Add the alias to the Vite config. Aliases that point at the file system need an absolute path, so build one from the config file's own location.
// vite.config.ts
import { defineConfig } from 'vite'
import { fileURLToPath, URL } from 'node:url'
export default defineConfig({
resolve: {
alias: {
'@': fileURLToPath(new URL('./src', import.meta.url)),
},
},
})3Verify
Restart the dev server and open a page that imports through the alias.
npx vite buildConfirmed by vite.dev
Cause 2 of 4
The alias path is relative, so Vite uses it as written
1Check
Look at the right-hand side of the alias. A value such as './src' or '/src' is not turned into a file system path.
grep -n "'@'" vite.config.*2Fix
Replace the relative value with an absolute one, as in the example above.
alias: {
'@': fileURLToPath(new URL('./src', import.meta.url)),
}3Verify
Run the build again and confirm the error is gone.
npx vite buildConfirmed by vite.dev
Cause 3 of 4
A separate vitest.config file replaced the Vite config
1Check
When both vite.config and vitest.config exist, Vitest uses the second one and ignores the first, so the alias never reaches the tests.
ls vite.config.* vitest.config.*2Fix
Merge the Vite config into the Vitest config, or move the test options into vite.config under a test key and delete the second file.
// vitest.config.ts
import { defineConfig, mergeConfig } from 'vitest/config'
import viteConfig from './vite.config'
export default mergeConfig(viteConfig, defineConfig({
test: { environment: 'jsdom' },
}))3Verify
Run the tests once.
npx vitest runConfirmed by vitest.dev
Cause 4 of 4
tsconfig paths is set, but Vite is not told to use it
1Check
TypeScript paths only tells the type checker how to resolve an import. It does not change what runs, so another tool must provide the same mapping.
grep -n -B1 -A3 "paths" tsconfig*.json2Fix
Keep the mapping in both places: the alias in the Vite config, and the matching paths entry in tsconfig so the editor and tsc agree.
// tsconfig.json (compilerOptions)
"paths": { "@/*": ["./src/*"] }3Verify
Run the type check and the build.
npx tsc --noEmit
npx vite buildConfirmed by typescriptlang.org
How do I stop it coming back?
- Define the alias once in the Vite config and mirror it in tsconfig paths in the same commit.
- Keep one config file for Vite and Vitest, or use mergeConfig, so the two never drift.
- Use an absolute path for every alias that points into the project.
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.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
Related fixes
Web apps
tsconfig rejects allowImportingTsExtensions
An error that allowImportingTsExtensions needs noEmit or emitDeclarationOnly
allowImportingTsExtensions lets files import each other with .ts or .tsx extensions, and TypeScript only allows it together with noEmit or emitDeclarationOnly.
2 causes, each with a fixWeb apps
Cypress refuses to start with 'Your configFile is invalid'
Your configFile threw an error from: /path/to/cypress.config.ts
Cypress could not load cypress.config.js or .ts, or found something wrong in it.
5 causes, each with a fixWeb apps
ESLint cannot decide which copy of the @typescript-eslint plugin to use
The message lists two file paths for the same plugin, each with the name of the config that loaded it
ESLint found the same plugin at two different file paths and will not pick one.
3 causes, each with a fixWeb apps
ESLint says it cannot resolve a path to a module that does exist
Unable to resolve path to module 'react'. import/no-unresolved
import/no-unresolved fails when eslint-plugin-import cannot find the file or package on disk with its resolver.
4 causes, each with a fixWeb apps
ESLint was configured to run using parserOptions.project, but the file is not in the TSConfig
However, that TSConfig does not include this file
Type-aware linting needs every linted file to belong to a TypeScript project.
4 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 fix