vitest-dev/vitest · error · Error

Failed to resolve user-event package from ${previewDistRoot}

Error message

Failed to resolve user-event package from ${previewDistRoot}

What it means

When the `preview` provider is active, the virtual context module needs `@testing-library/user-event` to wire up `userEvent`. Vitest resolves that package starting from the provider's `distRoot`; if the resolver returns null it cannot inject `userEvent`, so it fails fast.

Source

Thrown at packages/browser/src/node/plugins/pluginContext.ts:95

  commands: {
    ${commandsCode}
  },
  config: __vitest_browser_runner__.config,
}
export const commands = server.commands
export const userEvent = createUserEvent(_userEventSetup)
export { page, cdp, locators, utils }
`
}

async function getUserEventImport(provider: BrowserProvider | undefined, resolve: (id: string, importer: string) => Promise<null | { id: string }>) {
  if (!provider || provider.name !== 'preview') {
    return 'const _userEventSetup = undefined'
  }
  const previewDistRoot = (provider as any).distRoot
  const resolved = await resolve('@testing-library/user-event', previewDistRoot)
  if (!resolved) {
    throw new Error(`Failed to resolve user-event package from ${previewDistRoot}`)
  }
  return `\
import { userEvent as _userEventSetup } from '${slash(`/@fs/${resolved.id}`)}'
`
}

View on GitHub (pinned to d568f8ce37)

Solutions

1. Install the package: `pnpm add -D @testing-library/user-event`.
2. Verify resolution: `node -e "console.log(require.resolve('@testing-library/user-event', { paths: ['<provider distRoot>'] }))"`.
3. For pnpm, ensure the package isn't locked behind `node-linker=hoisted=false` issues — add it to the workspace and rerun `pnpm install`.
4. If using a private registry, confirm the package downloaded correctly (clear `node_modules/.pnpm` and reinstall).

Example fix

// before — preview provider without user-event
pnpm add -D vitest @vitest/browser

// after
pnpm add -D vitest @vitest/browser @testing-library/user-event

import { createRequire } from 'node:module'
import { dirname } from 'pathe'

function userEventResolvableFrom(distRoot: string): boolean {
  try {
    createRequire(distRoot + '/package.json').resolve('@testing-library/user-event')
    return true
  } catch {
    return false
  }
}

When it happens

Trigger: Using `provider: 'preview'` and importing `vitest/browser` while `@testing-library/user-event` is not installed, is not resolvable from the provider's `distRoot`, or is shadowed by an incompatible version.

Common situations: Forgetting to install `@testing-library/user-event` for component testing with the preview provider; pnpm strict hoisting hiding the package from the provider's resolution root; a broken or partial install.

Related errors

• The "preview" provider doesn't support 'userEvent.dragAndDro
• Element not found: ${v.element}
• Cannot upload files outside of a test
• [vitest] Cannot resolve "${id}" imported from "${importer}"
• pretty-format: Option "theme" has a key "${key}" whose value

AI-assisted analysis of vitest-dev/vitest@d568f8ce37 (2026-08-03). Data as JSON: /data/errors/6e8aa26c5092d991.json. Report an issue: GitHub.