Cannot find module - misspelled path
If you receive an error that a module cannot be found, first verify the path is spelled correctly.
common-errors
23 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Cannot find module - tsconfig.json baseUrl not respected
Vite does not take into account tsconfig.json by default. If you rely on baseUrl in your tsconfig.json, you need to install vite-tsconfig-paths yourself. You can configure it in vitest.config.js by importing tsconfigPaths from 'vite-tsconfig-paths' and adding it to the plugins array in defineConfig.
vite-tsconfig-paths configuration example
To use vite-tsconfig-paths with Vitest, configure it like this: import { defineConfig } from 'vitest/config' import tsconfigPaths from 'vite-tsconfig-paths' export default defineConfig({ plugins: [tsconfigPaths()] })
Cannot find module - relative path workaround
Instead of using relative imports from root with baseUrl, you can rewrite paths to be relative to the current file location. For example, change 'import helpers from src/helpers' to 'import helpers from ../src/helpers'.
Avoid relative aliases in Vite configuration
Do not use relative aliases in Vite. Vite treats relative aliases as relative to the file where the import is instead of the root. Use absolute URLs instead. For example, instead of '@/': './src/', use '@/': new URL('./src/', import.meta.url).pathname.
Relative aliases configuration example
To fix relative aliases in Vitest config, use absolute URLs: import { defineConfig } from 'vitest/config' export default defineConfig({ test: { alias: { '@/': new URL('./src/', import.meta.url).pathname, } } })
Failed to Terminate Worker with pool: 'threads' and fetch
The 'Failed to Terminate Worker' error can happen when NodeJS's fetch is used with pool: 'threads'. The default pool: 'forks' does not have this issue. Switching back to 'forks' or using 'vmForks' will resolve it.
Custom package conditions not resolved by default
Vitest does not respect custom conditions in package.json exports or subpath imports by default. By default, Vitest will only use the import and default conditions. To make Vitest respect custom conditions, configure ssr.resolve.conditions in your Vitest config.
Configure custom package conditions
To make Vitest respect custom conditions in package.json exports and imports, configure ssr.resolve.conditions in your vitest.config.js file: import { defineConfig } from 'vitest/config' export default defineConfig({ ssr: { resolve: { conditions: ['custom', 'import', 'default'], }, }, })
ssr.resolve.conditions vs resolve.conditions
Vitest follows Vite's configuration convention: resolve.conditions applies to Vite's client environment (Vitest's browser mode, jsdom, happy-dom, or custom environments with viteEnvironment: 'client'). ssr.resolve.conditions applies to Vite's ssr environment (Vitest's node environment or custom environments with viteEnvironment: 'ssr'). Since Vitest defaults to the node environment which uses viteEnvironment: 'ssr', module resolution uses ssr.resolve.conditions.
Native code segfaults with pool: 'threads'
Running native NodeJS modules in pool: 'threads' can encounter segmentation faults and other cryptic native code errors like thread panics, abort traps, or unreachable code errors. This happens because native modules are often not built to be multi-thread safe.
Workaround native code segfaults - use pool: 'forks'
To fix segfaults and native code errors, switch to pool: 'forks' which runs test cases in multiple node:child_process instead of multiple node:worker_threads. Configure it in vitest.config.js with pool: 'forks' or use the CLI flag --pool=forks.
Unhandled Promise Rejection cause
Unhandled Promise Rejection occurs when a Promise rejects but no .catch() handler or await is attached to it before the microtask queue flushes. This is a JavaScript behavior, not specific to Vitest. A common cause is calling an async function without awaiting it.
Unhandled Promise Rejection example
Example of unhandled promise rejection: async function fetchUser(id) { const res = await fetch(`/api/users/${id}`) if (!res.ok) { throw new Error(`User ${id} not found`) } return res.json() } test('fetches user', async () => { fetchUser(123) // Error: fetchUser not awaited }) This will result in an unhandled rejection because fetchUser() is not awaited.
Fix Unhandled Promise Rejection - await the promise
To fix an unhandled promise rejection, await the promise so Vitest can catch the error: test('fetches user', async () => { await fetchUser(123) }) Alternatively, if you expect the call to throw, use expect().rejects: test('rejects for missing user', async () => { await expect(fetchUser(123)).rejects.toThrow('User 123 not found') })
Package works in app but fails in Vitest
Some packages work in an app build but fail in Vitest because they are only valid after a bundler has rewritten or resolved them. When Vitest externalizes a dependency, Node.js loads it directly, so Node's ESM and package rules apply. Common issues include packages that ship ESM syntax without type: module, use extensionless relative imports, have incorrect exports/imports/main/module entries, mix CommonJS and ESM incorrectly, or import non-JavaScript files.
Common package loading errors in Vitest
When a package fails to load in Vitest, you might see errors such as: Cannot find module './relative-path' imported from ..., Unexpected token 'export', Cannot use import statement outside a module, Module ... seems to be an ES Module but shipped in a CommonJS package, or Unknown file extension ".css".
Fix invalid packages - make Node.js loadable
When possible, fix the package so Node.js can load it directly: add type: module for ESM .js files, use .mjs extension, include explicit file extensions in ESM imports, and make sure exports points to files Node.js can load.
Inline broken packages in Vitest config
If you cannot fix a package itself, inline it so Vite handles it instead of passing it to Node.js as an external dependency. Inline the whole dependency chain that leads to the invalid package. Configure it in vitest.config.js: import { defineConfig } from 'vitest/config' export default defineConfig({ test: { server: { deps: { inline: ['wrapper-package', 'broken-package'], }, }, }, })
Use ssr.resolve.noExternal to inline packages
You can also use Vite's ssr.resolve.noExternal for the same purpose as server.deps.inline. Vitest merges ssr.resolve.noExternal into server.deps.inline, so this is useful when the dependency also needs to be bundled by Vite in SSR builds: import { defineConfig } from 'vitest/config' export default defineConfig({ ssr: { resolve: { noExternal: ['wrapper-package', 'broken-package'], }, }, })
Unhandled errors catching behavior
By default Vitest catches and reports all unhandled rejections, uncaught exceptions in Node.js and error events in the browser. This behavior can be disabled by manually catching them.
Ignoring unhandled errors
Use the dangerouslyIgnoreUnhandledErrors config option to ignore reported errors. Vitest will still report them but they won't affect the test result or exit code.
Testing uncaught errors with onTestFinished
test('my function throws uncaught error', async ({ onTestFinished }) => { const unhandledRejectionListener = vi.fn() process.on('unhandledRejection', unhandledRejectionListener) onTestFinished(() => { process.off('unhandledRejection', unhandledRejectionListener) }) callMyFunctionThatRejectsError() await expect.poll(unhandledRejectionListener).toHaveBeenCalled() })