vitejs/vite · error · Error

Failed to load `transformWithEsbuild`. It is deprecated and…

Error message

Failed to load `transformWithEsbuild`. It is deprecated and it now requires esbuild to be installed separately. If you are a package author, please migrate to `transformWithOxc` instead.

What it means

transformWithEsbuild is a deprecated escape hatch that now dynamically imports the 'esbuild' package. If that import throws (module not found / resolution failure), Vite rethrows with this message and the original error as cause. Vite itself migrated its default transform pipeline to oxc, so esbuild is no longer a transitive dependency.

Solutions

1. Migrate the calling code to transformWithOxc (the current Vite default) — recommended for package authors.
2. If you must keep esbuild, install it explicitly: `npm install esbuild` (or add to dependencies).
3. Remove any config that forces the esbuild plugin back into the pipeline (e.g. custom build.target shenanigans) unless esbuild is present.
4. Audit third-party plugins for transformWithEsbuild usage and update them.

Example fix

// before
import { transformWithEsbuild } from 'vite'
const res = await transformWithEsbuild(code, id)
// after
import { transformWithOxc } from 'vite'
const res = await transformWithOxc(code, id)

// Check esbuild availability before calling
async function canUseEsbuild() {
  try { await import('esbuild'); return true } catch { return false }
}
if (!await canUseEsbuild()) throw new Error('Install esbuild or migrate to transformWithOxc')

try {
  return await transformWithEsbuild(code, id, options)
} catch (e) {
  if (/Failed to load `transformWithEsbuild`/.test(e.message)) {
    return await transformWithOxc(code, id) // fallback path
  }
  throw e
}

When it happens

Trigger: Calling transformWithEsbuild(code, id) directly (e.g. a plugin or user config overriding esbuild transform), or having optimizeDeps.esbuildOptions / build target code paths that still route through the esbuild plugin, when 'esbuild' is not installed in node_modules.

Common situations: Upgrading to a Vite version that dropped the bundled esbuild, copying an old plugin that calls transformWithEsbuild, or a custom plugin using esbuild for JSX stripping. Package authors hitting this are explicitly told to migrate.

Related errors

• Unable to parse: .
• Failed to load PostCSS config
• oxc transform error
• oxc transform error
• Preprocessor dependency

AI-assisted analysis of vitejs/vite@b4d66fee14 (2026-08-11). Data as JSON: /api/errors/e509cdfcb8f91115. Report an issue: GitHub.

Appendix: source

Thrown at packages/vite/src/node/plugins/esbuild.ts:224

    ...options,
    loader,
    tsconfigRaw,
  }

  // Some projects in the ecosystem are calling this function with an ESBuildOptions
  // object and esbuild throws an error for extra fields
  // @ts-expect-error include exists in ESBuildOptions
  delete resolvedOptions.include
  // @ts-expect-error exclude exists in ESBuildOptions
  delete resolvedOptions.exclude
  // @ts-expect-error jsxInject exists in ESBuildOptions
  delete resolvedOptions.jsxInject

  let transform: typeof import('esbuild').transform
  try {
    transform = (await importEsbuild()).transform
  } catch (e) {
    throw new Error(
      'Failed to load `transformWithEsbuild`. ' +
        'It is deprecated and it now requires esbuild to be installed separately. ' +
        'If you are a package author, please migrate to `transformWithOxc` instead.',
      { cause: e },
    )
  }

  if (!ignoreEsbuildWarning) {
    warnTransformWithEsbuildUsageOnce()
  }

  try {
    const result = await transform(code, resolvedOptions)
    let map: SourceMap
    if (inMap && resolvedOptions.sourcemap) {
      const nextMap = JSON.parse(result.map)
      nextMap.sourcesContent = []
      map = combineSourcemaps(filename, [

View on GitHub (pinned to b4d66fee14)