Solución de problemas

Consulta la guía de solución de problemas de Rollup para obtener más información también.

Si estas sugerencias no funcionan, prueba colocando tus preguntas en las discusiones de GitHub o en el canal #help de ViteLand Discord.

CLI

Error: No se puede encontrar el módulo 'C:\foo\bar&baz\vite\bin\vite.js'

La ruta a la carpeta de tu proyecto puede incluir &, que no funciona con npm en Windows (npm/cmd-shim#45).

Necesitarás:

• Cambiar a otro gestor de paquetes (por ejemplo, pnpm, yarn)
• Eliminar & de la ruta a tu proyecto

Configuración

Este paquete es solo ESM

Cuando se importa un paquete solo ESM con require, ocurre el siguiente error:

No se pudo resolver "foo". Este paquete es solo ESM pero se intentó cargar con require.

Error [ERR_REQUIRE_ESM]: no se admite el uso de require() de un módulo ES /path/to/dependency.js desde /path/to/vite.config.js.
En su lugar, cambia la llamada a require de index.js en /path/to/vite.config.js a una importación dinámica import(), la cual está disponible en todos los módulos CommonJS.
En Node.js <=22, los archivos ESM no pueden cargarse mediante require() por defecto.

Aunque puede funcionar utilizando --experimental-require-module o en versiones de Node.js >22, o en otros entornos, aún se recomienda convertir tu configuración a ESM así:

• Añade "type": "module" al archivo package.json más cercano.
• Renombra vite.config.js/vite.config.ts a vite.config.mjs/vite.config.mts

Servidor de desarrollo

Las solicitudes se congelan para siempre

Si estás utilizando Linux, los límites del descriptor de archivo y los límites de inotify pueden estar causando el problema. Como Vite no empaqueta la mayoría de los archivos, los navegadores pueden solicitar muchos archivos que requieren muchos descriptores de archivo, superando el límite.

Para resolver esto:

• Aumenta el límite del descriptor de archivo con ulimit

  # Verifica el límite actual
  $ ulimit -Sn
  # Cambia el límite (temporal)
  $ ulimit -Sn 10000 # Es posible que también debas cambiar el límite estricto
  # Reinicia tu navegador

• Aumenta los siguientes límites relacionados con inotify con sysctl

  # Verifica el límite actual
  $ sysctl fs.inotify
  # Cambia el límite (temporal)
  $ sudo sysctl fs.inotify.max_queued_events=16384
  $ sudo sysctl fs.inotify.max_user_instances=8192
  $ sudo sysctl fs.inotify.max_user_watches=524288

  Si los pasos anteriores no funcionan, puedes intentar agregar DefaultLimitNOFILE=65536 como una configuración sin comentarios a los siguientes archivos:

• /etc/systemd/system.conf

• /etc/systemd/user.conf

Para Linux Ubuntu, es posible que debas agregar la línea * - nofile 65536 al archivo /etc/security/limits.conf en lugar de actualizar los archivos de configuración de systemd.

Ten en cuenta que estas configuraciones persisten pero se requiere un reinicio.

Alternativamente, si el servidor se está ejecutando dentro de un devcontainer de VS Code, la solicitud puede parecer bloqueada. Para solucionar este problema, consulta Contenedores de desarrollo / Redirección de puertos en VS Code.

Las solicitudes de red dejan de cargarse

Al usar un certificado SSL autofirmado, Chrome ignora todas las directivas de almacenamiento en caché y vuelve a cargar el contenido. Vite se basa en estas directivas de almacenamiento en caché.

Para resolver el problema, utiliza un certificado SSL de confianza.

Consulta: Problemas de caché, Problemas de Chrome

MacOS

Puedes instalar un certificado de confianza a través de la CLI con este comando:

security add-trusted-cert -d -r trustRoot -k ~/Library/Keychains/login.keychain-db your-cert.cer

O importándolo a la aplicación Acceso a Llaveros y actualizando la configuración de confianza del certificado a "Confiar siempre".

431 Campos de la Cabecera de la Petición Demasiado Grandes

Cuando el servidor / el servidor WebSocket recibe una cabecera HTTP grande, la petición será descartada y se mostrará la siguiente advertencia.

El servidor ha respondido con el código de estado 431. Ver https://es.vite.dev/guide/troubleshooting.html#_431-campos-de-la-cabecera-de-la-peticion-demasiado-grandes.

Esto se debe a que Node.js limita el tamaño del encabezado de la solicitud para mitigar CVE-2018-12121.

Para evitar esto, intenta reducir el tamaño del encabezado de la solicitud. Por ejemplo, si la cookie es larga, elimínala. O puedes usar --max-http-header-size para cambiar el tamaño máximo de la cabecera.

Contenedores de desarrollo / Redirección de puertos en VS Code

Si estás utilizando un contenedor de desarrollo o la función de redirección de puertos en VS Code, es posible que necesites configurar la opción server.host en 127.0.0.1 dentro de la configuración para que funcione correctamente.

Esto se debe a que la función de redirección de puertos en VS Code no admite IPv6.

Consulta el #16522 para más detalles.

HMR

Vite detecta un cambio de archivo pero el HMR no funciona

Es posible que estés importando un archivo con un caso diferente. Por ejemplo, src/foo.js existe y src/bar.js contiene:

import './Foo.js' // debe ser './foo.js'

Problema relacionado: #964

Vite no detecta un cambio de archivo

Si estás ejecutando Vite con WSL2, Vite no puede ver los cambios de archivos en algunas condiciones. Ver opción server.watch.

Ocurre una recarga completa en lugar de HMR

Si Vite o un plugin no manejan HMR, se producirá una recarga completa, ya que es la única forma de actualizar el estado.

Si se maneja HMR pero está dentro de una dependencia circular, también se realizará una recarga completa para recuperar la orden de ejecución. Para resolver esto, intenta romper el ciclo. Puedes ejecutar vite --debug hmr para registrar la ruta de dependencia circular si un cambio de archivo la activó.

Gran cantidad de actualizaciones de HMR en la consola

Esto puede deberse a una dependencia circular. Para resolver esto, intenta romper el bucle.

Compilación

El archivo integrado no funciona debido a un error de CORS

Si la salida del archivo HTML se abrió con el protocolo file, los scripts no se ejecutarán con el siguiente error.

El acceso a la secuencia de comandos en 'file:///foo/bar.js' desde el origen 'null' ha sido bloqueado por la política de CORS: las solicitudes de origen cruzado solo se admiten para esquemas de protocolo: http, data, isolated-app, chrome-extension, chrome, https, chrome-untrusted.

Solicitud de origen cruzado bloqueada: la política del mismo origen no permite leer el recurso remoto en file:///foo/bar.js. (Razón: solicitud CORS no http).

Consulta Motivo: la solicitud CORS no es HTTP - HTTP | MDN para obtener más información sobre por qué sucede esto.

Debes acceder al archivo con el protocolo http. La forma más fácil de lograr esto es ejecutar npx vite preview.

Error de no such file or directory debido a la sensibilidad de mayúsculas y minúsculas

Si encuentras errores como ENOENT: no such file or directory o Module not found, esto a menudo ocurre cuando tu proyecto fue desarrollado en un sistema de archivos insensible a mayúsculas y minúsculas (Windows / macOS) pero construido en un sistema de archivos sensible a mayúsculas y minúsculas (Linux). Por favor, asegúrate de que los imports tengan las mayúsculas y minúsculas correctas.

Error Failed to fetch dynamically imported module

TypeError: Failed to fetch dynamically imported module

Este error ocurre en varios casos:

• Despliegue de versiones
• Condiciones de red pobres
• Extensiones del navegador bloqueando las solicitudes

Despliegue de versiones

Cuando despliegas una nueva versión de tu aplicación, el archivo HTML y los archivos JS siguen referenciando nombres de fragmentos antiguos que fueron eliminados en la nueva despliegue. Esto ocurre cuando:

1. Los usuarios tienen una versión antigua de tu aplicación en caché en su navegador
2. Despliegas una nueva versión con nombres de fragmentos diferentes (debido a cambios de código)
3. El HTML en caché intenta cargar fragmentos que ya no existen

Si estás utilizando un framework, consulta su documentación primero ya que puede tener una solución integrada para este problema.

Para resolver esto, puedes:

• Mantener los fragmentos antiguos temporalmente: Considera mantener los fragmentos anteriores de la despliegue anterior durante un período para permitir que los usuarios en caché transiten de manera suave.
• Implementa un service worker: Implementa un service worker que haga prefetch de todos los activos y los cachea.
• Hacer prefetch de los fragmentos dinámicos: Ten en cuenta que esto no ayuda si tu archivo HTML está en caché por el navegador debido a la cabecera Cache-Control.
• Implementa un manejo de errores de carga: Implementa un manejo de errores para las importaciones dinámicas para recargar la página cuando los fragmentos faltan. Consulta Manejo de errores de carga para más detalles.

Condiciones de red pobres

Este error puede ocurrir en entornos de red inestables. Por ejemplo, cuando la solicitud falla debido a errores de red o downtime del servidor.

Ten en cuenta que no puedes reintentar la importación dinámica debido a limitaciones del navegador (whatwg/html#6768).

Extensiones del navegador bloqueando las solicitudes

Este error también puede ocurrir si las extensiones del navegador (como bloqueadores de publicidad) están bloqueando la solicitud.

Podría ser posible solucionarlo seleccionando un nombre de fragmento diferente por build.rollupOptions.output.chunkFileNames, ya que estas extensiones a menudo bloquean las solicitudes basadas en nombres de archivos (por ejemplo, nombres que contienen ad, track).

Dependencias optimizadas

Dependencias preempaquetadas desactualizadas al vincularlas a un paquete local

La clave hash utilizada para invalidar las dependencias optimizadas depende del contenido del package lock, los parches aplicados a las dependencias y las opciones en el archivo de configuración de Vite que afecta el empaquetado de módulos de Node. Esto significa que Vite detectará cuándo se invalida una dependencia mediante una característica como invalidaciones de npm, y volverá a empaquetar las dependencias en el próximo inicio del servidor. Vite no invalidará las dependencias cuando utilices una función como npm link. En caso de que vincules o desvincules una dependencia, deberás forzar la reoptimización en el próximo inicio del servidor usando vite --force. En su lugar, recomendamos usar invalidaciones, que ahora son compatibles con todos los gestores de paquetes (consulta también invalidaciones de pnpm y resoluciones de yarn).

Cuellos de Botella en el Rendimiento

Si sufres cuellos de botella en el rendimiento de la aplicación que resultan en tiempos de carga lentos, puedes iniciar el inspector integrado de Node.js con tu servidor de desarrollo de Vite o al compilar tu aplicación para crear el perfil de la CPU:

dev server

vite --profile --open

build

vite build --profile

Servidor de desarrollo de Vite

Una vez que la aplicación se abra en el navegador, simplemente espera a que termine de cargar y luego regresa a la terminal y presiona la tecla p (detendrá el inspector de Node.js), luego presiona la tecla q para detener el servidor de desarrollo.

El inspector de Node.js generará vite-profile-0.cpuprofile en la carpeta raíz, ve a https://www.speedscope.app/ y sube el perfil de la CPU usando el botón BROWSE para inspeccionar el resultado.

Puedes instalar vite-plugin-inspect, que te permite inspeccionar el estado intermedio de los plugins de Vite y también puede ayudarte a identificar qué plugins o middlewares están generando el cuello de botella en tus aplicaciones. El plugin se puede usar tanto en modo de desarrollo como compilado. Consulta el archivo readme para obtener más detalles.

Otros

Módulo externalizado para compatibilidad con navegadores

Cuando usas un módulo de Node.js en el navegador, Vite mostrará la siguiente advertencia.

El módulo "fs" se ha externalizado para compatibilidad con el navegador. No se puede acceder a "fs.readFile" en el código del cliente.

Esto se debe a que Vite no reinserta automáticamente los módulos de Node.js.

Recomendamos evitar el uso de módulos de Node.js para código del navegador para reducir el tamaño del paquete, aunque puedes agregar polyfills manualmente. Si el módulo se importa desde una biblioteca de terceros (que está destinado a ser utilizado en el navegador), se recomienda informar el problema a la biblioteca respectiva.

Se produce un error de sintaxis/error de tipo

Vite no puede manejar y no admite código que solo se ejecuta en modo no estricto (modo desapercibido). Esto se debe a que Vite usa ESM y siempre está en modo estricto dentro de ESM.

Por ejemplo, es posible que veas estos errores.

[ERROR] Las declaraciones With no se pueden usar con el formato de salida "esm" debido al modo estricto

TypeError: no se puede crear la propiedad 'foo' en booleano 'false'

Si este código se usa dentro de las dependencias, podrías usar patch-package (o yarn patch o pnpm patch) para una trampilla de escape.

Extensiones del navegador

Algunas extensiones del navegador (como los bloqueadores de publicidad) pueden impedir que el cliente de Vite envíe solicitudes al servidor de desarrollo de Vite. Puedes ver una pantalla en blanco sin errores registrados en este caso. También puedes ver el siguiente error:

TypeError: No se pudo cargar dinámicamente el módulo importado

Prueba a deshabilitar las extensiones si tienes este problema.

Enlaces cruzados entre unidades en Windows

Si hay enlaces cruzados entre unidades en tu proyecto en Windows, es posible que Vite no funcione.

Un ejemplo de enlaces cruzados entre unidades son:

• una unidad virtual enlazada a una carpeta mediante el comando subst
• un enlace simbólico/junción a una unidad diferente mediante el comando mklink (por ejemplo, la caché global de Yarn)

Issue relacionada: #10802