Vitest alias resolution "Failed to resolve import @/..." in CI

By Kaveh Alemi·Latchkey

Vitest resolves imports through Vite, not TypeScript, so paths aliases in tsconfig are ignored unless you mirror them. Add them to resolve.alias or use the vite-tsconfig-paths plugin, or @/... imports fail to resolve in CI.

What this error means

Tests fail with "Failed to resolve import '@/utils' from 'src/foo.test.ts'. Does the file exist?" while type-checking in the IDE looks fine.

Error: Failed to resolve import "@/utils/format" from "src/foo.test.ts".
Does the file exist?

Common causes

tsconfig paths are not applied at runtime

TypeScript paths only affect type checking. Vite/Vitest need the alias declared separately to resolve the module.

The alias plugin is not installed in CI

The config relies on vite-tsconfig-paths, but it is missing from the CI dependency tree, so aliases are not wired up.

How to fix it

Declare aliases for Vite/Vitest

1. Add resolve.alias entries that mirror your tsconfig paths, or install vite-tsconfig-paths.
2. Ensure the plugin (if used) is in devDependencies and installed by npm ci.
3. Re-run so imports resolve at runtime.

import { defineConfig } from 'vitest/config'
import path from 'node:path'
export default defineConfig({
  resolve: { alias: { '@': path.resolve(__dirname, 'src') } },
})

Or use the tsconfig-paths plugin

Wire tsconfig paths automatically with the Vite plugin so both stay in sync.

import tsconfigPaths from 'vite-tsconfig-paths'
export default defineConfig({ plugins: [tsconfigPaths()] })

How to prevent it

• Mirror tsconfig paths in resolve.alias or via the plugin.
• Keep the alias plugin in devDependencies.
• Run the suite from a clean install so alias gaps surface.

Frequently asked questions

Related guides

References

• GitHub Actions documentation